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.
...
- add() provides a netid, nodename, other arguments to create a node
- delete() provide a nodename, tell NetBill 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
Table of Contents |
---|
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
Note |
---|
We need charge_cd as one of the input arguments. - Added, db692 Existing Oracle API: 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:
...
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 - 11:59AM3: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:
NoneNONE
0000INCR0000
0030INCR0030
0100INCR0100
0130INCR0130
0200INCR0200
0230INCR0230
0300INCR0300
0330INCR0330
0400INCR0400
0430INCR0430
0500INCR0500
0530INCR0530
0600INCR0600
0630INCR0630
0700INCR0700
0730INCR0730
0800INCR0800
0830INCR0830
0900INCR0900
0930INCR0930
1000INCR1000
1030INCR1030
1100INCR1100
1200INCR1130
1230INCR1200
1300INCR1230
1330INCR1300
1400INCR1330
1430INCR1400
1500INCR1430
1530INCR1500
1600INCR1530
1630INCR1600
1700INCR1630 1730
INCR1730
1800INCR1800
1830INCR1830
1900INCR1900
1930INCR1930
2000INCR2000
2030INCR2030
2100INCR2100
2130INCR2130
2200INCR2200
2230INCR2230
2300INCR2300
2330INCR2330
delete()
Arguments for delete:
netid of owner
nodename (needs to be unique, and exist)
datestamp for date to delete, formatted as Oracle date (31-JAN-132013). This is awkward for ServiceNow, but native for NetBill. Furthermore, ServiceNow already has a method that does formats months in this way for previous Oracle interactions.
Note |
---|
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 |
Info |
---|
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
Note |
---|
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) -2 netid invalid -n: a database error occured |
Don't use the next method, because getBillingViaSN is exactly what we need.
Note |
---|
existing oracle API: FUNCTION getSrvcChargeInfo (a_netid IN VARCHAR2, |
Note |
---|
What is a_service_cd, and how should it be formatted? a_service_cd='CB' |
getNodeList()
Arguments for getNodeList:
netid of owner
...
- 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
Note |
---|
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 |
Note |
---|
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'. |
Info |
---|
If you want a list of active nodes, use "status_cd in ('A', 'RL'). 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 NOT exist 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
Note |
---|
Existing oracle API: PROCEDURE getCBDetail (a_node_name IN VARCHAR2,
PROCEDURE getCBNodeDetailViaSN (a_node_name IN VARCHAR2, 0 success -2 nodename is invalid |
update()
Arguments for update:
netid of ownercharge_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
Note |
---|
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, 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.
Info |
---|
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
- 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
stringNUMBER 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. - 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
Note |
---|
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. |
Info |
---|
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.
Info |
---|
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.
Info |
---|
Test plans and scripts must be created and executed in each environment. Service Introduction tasks must be completed. |