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
add()
Arguments for add:
netid of owner
nodename (needs to be unique, and NOT exist already in the system)
client category (DS,MW,WS)
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? Can it be fastTrack account? ---no.
Existing Oracle API:
FUNCTION createCBAccount (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,
a_fast_track IN VARCHAR2)
This function will create a CB node on the default server.
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.
PTAEO details
PTAEO consists of five strings:
- project
- task
- award
- expenditure
- 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:
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
Please use format INCR1130, INCR1100 etc. - Done, db692
We've heard from Jim Owen that this list is incomplete. He is going to email us with the complete list. - List has been completed, db692
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.
we don't need netid as input argument. confirm date format? ; at last meeting Rod said he would prefer a four-digit year. - db692
Existing Oracle API: FUNCTION expireCBAccount (a_node_name IN VARCHAR2, a_expire_date IN DATE)
New ServiceNow API: FUNCTION expireCBAccountViaSN (a_node_name IN VARCHAR2, a_expire_date IN DATE) RETURN NUMBER
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
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?
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=?
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?
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:
nodename (needs to be unique, and NOT 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);
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)
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.
Outstanding questions
- 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 that is returned from getSrvcChargeInfo(). Push it back to NetAdmin on update() and add() methods.
- 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 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.
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.