ITS backup service API, communicating with NetAdmin

Owned by David Backeberg (Unlicensed)
Last updated: Dec 13, 2013Version comment
8 min read

We need a new API for communicating START Replacement forms for Backup against NetBill/NetAdmin.

There is already an old API for talking between old START and NetBill/NetAdmin, but we are creating a new interface as we are changing the arguments.

From the perspective of ServiceNow, we need the methods:

  • add() provides a netid, nodename, other arguments to create a node
  • delete() provide a nodename, tell NetAdmin to delete the record
  • getBilling() provide a netid, receive whether or not PTAEO required
  • getNodeList() provide a netid, receive a list containing zero or more nodename(s) that are associated with that netid
  • getNodeDetails() provide a nodename, receive the details for that nodename
  • update() provide a nodename, provide arguments to change on the node

WSDL details

Kazi has provided a WSDL conforming to the SPEC defined here: 

add()

Arguments for add:
netid of owner
nodename (needs to be unique, and NOT exist already in the system)
client category (DS,MW,WS). This field is called "Policy Group" on the netAdmin API.

charge code (charge_cd which comes back in a response to getBilling())
Client OS (Windows, Mac, Unix)
interval (backup time, or never)
PTAEO, passed as five separate strings

  We need charge_cd as one of the input arguments. - Added, db692
Should default server be used to create this CB node, client domain to default server mapping? - Jim Owen says "two defaults. There is a default for servers and a default for workstations (managed or not managed). Should be a default in netadmin that can be changed."
Can it be fastTrack account? ---no.

Existing Oracle API:
FUNCTION createCBAccountViaSN (a_netid        IN VARCHAR2,
                            a_node_name    IN VARCHAR2,
                            a_policy_group IN VARCHAR2,
                            a_time_slot    IN VARCHAR2,
                            a_os           IN VARCHAR2,
                            a_charge_cd    IN NUMBER,
                            a_project      IN VARCHAR2,
                            a_task         IN VARCHAR2,
                            a_award        IN VARCHAR2,
                            a_org          IN VARCHAR2)

This function will create a CB node on the default server.

Returns

0 success

-1 duplicate entry. Request already made or account already exists.

-2 invalid netid

-3  invalid chargecode

-4 account / node already exists

-5 nodename has space (no spaces allowed)

-6 server invalid

-7 create pin error

-13 account exists but is locked

-99 netid is not linked

-n database error occurred

Add method needs to return an error code indicating whether or not the add request was accepted, and for errors should indicate the problem with the data.

What is a policy_group? A policy group is the same thing as a Client Category: DS,MW,WS

PTAEO details

PTAEO consists of five strings:

  1. project
  2. task
  3. award
  4. expenditure
  5. organization

Note that it's superfluous for us to pass around the Expenditure code. The E code is consistent for all Central Campus Backup items, thus the value will always be '832170'. We could drop this value from being passed, but for future flexibility we should leave it in the API.

Interval, possible values:

Interval is coded as a string. These values are shown to the user:

None – I will backup manually
12:00AM – 12:29AM
12:30AM – 12:59AM
1:00AM – 1:29AM
1:30AM – 1:59AM
2:00AM – 2:29AM
2:30AM – 2:59AM
3:00AM – 3:29AM
3:30AM – 3:59AM
4:00AM – 4:29AM
4:30AM – 4:59AM
5:00AM – 5:29AM
5:30AM – 5:59AM
6:00AM – 6:29AM
6:30AM – 6:59AM
7:00AM – 7:29AM
7:30AM – 7:59AM
8:00AM – 8:29AM
8:30AM – 8:59AM
9:00AM – 9:29AM
9:30AM – 9:59AM
10:00AM – 10:29AM
10:30AM – 10:59AM
11:00AM – 11:29AM
11:30AM – 11:59AM
12:00PM - 12:29PM
12:30PM - 1:00PM
1:30PM - 1:59PM
2:00PM - 2:29PM
2:30PM - 2:59PM
3:00PM - 3:29PM
3:30PM - 3:59PM
4:00PM - 4:29PM
4:30PM - 4:59PM
5:00PM - 5:29PM
5:30PM - 5:59PM
6:00PM - 6:29PM
6:30PM - 6:59PM

7:30PM - 7:59PM
8:00PM - 8:29PM
8:30PM - 8:59PM
9:00PM - 9:29PM
9:30PM - 9:59PM
10:00PM - 10:29PM
10:30PM - 10:59PM
11:00PM - 11:29PM
11:30PM - 11:59PM 

We will encode these for passing back and forth as zero-padded, military time, first four characters of the string to the api:

NONE
INCR0000
INCR0030
INCR0100
INCR0130
INCR0200
INCR0230
INCR0300
INCR0330
INCR0400
INCR0430
INCR0500
INCR0530
INCR0600
INCR0630
INCR0700
INCR0730
INCR0800
INCR0830
INCR0900
INCR0930
INCR1000
INCR1030
INCR1100
INCR1130
INCR1200
INCR1230
INCR1300
INCR1330
INCR1400
INCR1430
INCR1500
INCR1530
INCR1600
INCR1630

INCR1730
INCR1800
INCR1830
INCR1900
INCR1930
INCR2000
INCR2030
INCR2100
INCR2130
INCR2200
INCR2230
INCR2300
INCR2330

delete()

Arguments for delete:
nodename (needs to be unique, and exist)
datestamp for date to delete, formatted as Oracle date (31-JAN-2013). This is awkward for ServiceNow, but native for NetBill. Furthermore, ServiceNow already has a method that formats months in this way for previous Oracle interactions.

New ServiceNow API: FUNCTION expireCBAccountViaSN (a_node_name    IN VARCHAR2,   a_expire_date  IN VARCHAR2)  RETURN NUMBER

 

a_expire_date input expected format:MM/DD/YYYY

0 success

-10 cb node does not exist

-n database error occurred

You must pass in an Oracle date.  No time component.  WebMethods must convert whatever input is received from ServiceNow.  4 digit year is STRONGLY recommended. - rng3

Delete method needs to return an error code indicating whether or not the delete request was accepted, and for errors should indicate the problem with the data.

getBilling()

Arguments for getBilling:
netid of owner

getBilling method needs to return an error code indicating whether or not the getBilling request was accepted. If no error, also needs to return:

whether a PTAEO is required

It would be best to call the existing Oracle API:

 

FUNCTION getBillingViaSN ( a_netid IN VARCHAR2,

a_charge_code OUT NUMBER,

a_ptaeo_required OUT VARCHAR2)
RETURN NUMBER

0 request successful

-2 netid invalid

-n: a database error occured 

 

Don't use the next method, because getBillingViaSN is exactly what we need.

 

existing oracle API:

FUNCTION getSrvcChargeInfo (a_netid             IN  VARCHAR2,
                              a_service_cd           IN  VARCHAR2,
                              a_expenditure_type  OUT VARCHAR2,
                              a_charge_code       OUT NUMBER,
                              a_student_indicator OUT VARCHAR2,
                              a_charge_code_name  OUT VARCHAR2,
                              a_ptaeo_required    OUT VARCHAR2)

What is a_service_cd, and how should it be formatted? a_service_cd='CB'


getNodeList()

Arguments for getNodeList:
netid of owner

getNodeList method needs to return an error code indicating whether or not the getNodeset request was accepted. If no error, also needs to return:

  • a count of nodes. zero or more.
  • a comma-delimited list, containing zero or more nodenames
    each nodename is received in a single string, comma separated, no spaces

We have a view for this. ViewName:smart.YUSTART_CB_DETAILS_V

select node_name from smart.yustart_cb_details_v where owning_netid=?      This returns all nodes one owner netid owns. To filter node list by status,

select node_name from smart.yustart_cb_details_v where owning_netid=? and status_cd=? status_cd can be 'A'-Active, 'RA'-Request Active,'RL'-Request Lock (still active),'L'-Locked(inactive),'RD'-Request Delete (inactive),'D'-Deleted

We only want to query active nodes, so we will set status_cd='A'
We only want back a list of nodenames. 

Need to know the exact flags to set. We want only Active nodes, owned by the netid. What is the flag we should set for status_cd? 'A'.


If you want a list of active nodes, use "status_cd in ('A', 'RL').

For the purposes of later calling the update() and delete() method we will want to do a getNodeList against just the 'A' status_cd nodes.

RL is locked, and you cannot make a change on it. 

RA has not been created yet, so you can't perform any action on it.

L, RD and D are already closed, so you can't take further action on them.

 

 

Sample nodename strings

  • "tanner,cooper,radar"
  • "" (empty set)
  • "zuse"

getNodeDetails()

Arguments for getNodeDetails:
nodename of node

getNodeDetails method needs to return an error code indicating whether or not the getNodeDetails request was accepted. If no error, also needs to return:

  • returns:
    return code with possible error message that node does not exist
    nodename (needs to be unique, and EXIST already in the system)
    client category (DS,MW,WS)
    Client OS (Windows, Mac, Unix)
    interval (backup time, or never)
    PTAEO, passed as five separate strings

 

Existing oracle API:

PROCEDURE getCBDetail (a_node_name      IN VARCHAR2,
         a_parent_netid    OUT VARCHAR2,
       a_owning_netid     OUT VARCHAR2,
       a_status_cd        OUT VARCHAR2,
       a_policy_group_cd    OUT VARCHAR2,
       a_policy_group_desc     OUT VARCHAR2,
       a_time_slot_cd     OUT VARCHAR2,
       a_time_slot_desc       OUT VARCHAR2,
       a_early_late_option     OUT VARCHAR2,
       a_os_cd         OUT VARCHAR2,
       a_os_desc      OUT VARCHAR2,
       a_usage       OUT NUMBER,
       a_agreement_cd        OUT NUMBER,
       a_agreement_desc       OUT VARCHAR2,
       a_debit_project       OUT VARCHAR2,
       a_debit_task        OUT VARCHAR2,
       a_debit_award     OUT VARCHAR2,
       a_debit_org        OUT VARCHAR2,
       a_requested_date       OUT DATE,
       a_created_date     OUT DATE,
       a_requested_end_date    OUT DATE,
       a_end_date      OUT DATE,
       a_requested_delete_date OUT DATE,
       a_delete_date     OUT DATE,
       a_last_verified_date    OUT DATE,
       a_pin       OUT VARCHAR2);


NEW METHOD

PROCEDURE getCBNodeDetailViaSN (a_node_name      IN VARCHAR2,
                a_policy_group_cd    OUT VARCHAR2,
       a_time_slot_cd     OUT VARCHAR2,
       a_os_cd         OUT VARCHAR2,
       a_debit_project       OUT VARCHAR2,
       a_debit_task        OUT VARCHAR2,
       a_debit_award     OUT VARCHAR2,
       a_debit_org        OUT VARCHAR2,
);

RETURNS number

0 success

-2 nodename is invalid 

update()

Arguments for update:
charge_code (gathered from a previous call to getSrvcChargeInfo() )
nodename (needs to be unique, and already exist)

client category (DS,MW,WS)
Client OS (Windows, Mac, Unix)
interval (backup time, or never)
PTAEO, passed as five separate strings

 

We need charge_cd as one of the input arguments, we don't netid as input argument.

Existing oracle API:

FUNCTION updateCBAccount (a_node_name    IN VARCHAR2,
                            a_charge_cd    IN NUMBER,
                            a_project      IN VARCHAR2,
                            a_task         IN VARCHAR2,
                            a_award        IN VARCHAR2,
                            a_org          IN VARCHAR2,
       a_msg          OUT VARCHAR2)

new:

FUNCTION updateCBAccountViaSN (a_node_name    IN VARCHAR2,
                            a_charge_cd    IN NUMBER,
                            a_project      IN VARCHAR2,
                            a_task         IN VARCHAR2,
                            a_award        IN VARCHAR2,
                            a_org          IN VARCHAR2) 
RETURN number

0 success

-3 charge code invalid

-5 nodename has space

-10 nodename is invalid

-n database error occurred 

update method needs to return an error code indicating whether or not the add request was accepted, and for errors should indicate the problem with the data.

Updates are only applicable to update the PTAEO. End users cannot/do not need to select the Charge Code as that happens automatically.

Accounts using a Charge Code of 1 may have the PTAEO changed. All others should rejected because there is nothing to change.

Outstanding questions

  1. What's a charge code (name and / or number)? Do I need to pass that with everything I send back and forth to netbill? ANSWER: It's a string NUMBER that is returned from getSrvcChargeInfo(). Push it back to NetAdmin on update() and add() methods.  The interface also refers to this as an agreement code.  
  2. Why would we care whether or not somebody is a student? Is there relevance to billing? ServiceNow already knows this information, and apparently NetBill already knows also. Do we really need to pass that back and forth? ANSWER: The answer is complicated. The short answer is that a student shouldn't own a backup system, but they may do so on behalf of a staff member, and they may also own one if they were a staff member and then their status changed to student. So the long answer is no, we don't care.

Process

Each group has responsibilities to get this process moving.

DBA group

DBA group needs to provide a utility account to Oracle for granting access. The account needs to work in ACS3, ACS2, ACS1 Oracle instances. The account will be called wm_service_now.

made the request to DBAs: RITM0075694

Backeberg heard back from Norm Morales that he needs to know exactly which methods should be used for the purposes of granting rights on ACS1,ACS2,ACS3. Perhaps somebody from Rod's group can meet with Norm to work this out.

Rod's group will grant appropriate access as part of our deployment. All Norman needs to know is that the account will not own any objects.

Rod Gustavson's group

We need Rod's group to review the API as specified and confirm that this seems to be complete and sufficient for CRUD methods on these records.

We need new interface to NetBill to conform with the API as specified here. Note, that it seems the existing methods are sufficient. Instead, we just need to build up WebMethods API to talk to the existing design. There doesn't need to be substantial rework here.

We only need one new method for add. We will keep the other methods in place so they will continue to operate.

Minor changes are needed to other methods within NetAdmin to support the additional default server logic.

New rows must be added to the timeslots for each server.

New servers must be added to the servers table.

Deployment scripts must be created.

Unit testing of any modified procedure or any procedure relying upon a modified procedure will be done.

 

Kazi's group.

We need new Webmethods SOAP / XML api to bridge between the Oracle environment of NetBill and the ServiceNow SOAP interface. Kazi's group cannot begin until Rod's work is nearly completed. Kazi will need method names to bind to in Oracle.

Jim's group

Jim's group needs to get the instance names of TSM to Rod's group. Jim's group may need to provide a test instance of TSM for verifying end-to-end functionality of SN -> webmethods -> netbill -> TSM.

David Backeberg's group

Create and maintain specification for API. Request Oracle account from DBAs. Create and maintain task list for backup automation project.

Test plans and scripts must be created and executed in each environment.

Service Introduction tasks must be completed.