Alemba Classic API
Transactions are exposed via the web service. To use the Classic API, all transactions must be completed using the web service provided.
Limited Support/End of Life Capabilities
The Classic API has been replaced by the Alemba RestFul API. While we will continue to support the Classic API for clients that are still using it, no further development will be done.
If you need to request a hotfix or support for these features, please contact Alemba Support
ASM has two Application Programming Interfaces (or APIs), which enable you to develop programs that automate many common ASM transactions. This section of the documentation deals with the Classic API. For more information on the RESTful Alemba API, see here.
For information on how to develop code to call a web service, refer to the documentation for your chosen programming language.
The Classic API has been deprecated in favor of the Alemba API. While you are still able to use the Classic API, support is no longer provided.
Using Classic API Transactions
All transactions must be executed by a full analyst with a valid Session ID. A Session ID is a short alphanumeric string that is generated when an analyst logs into ASM. The Session ID identifies the analyst as they navigate between pages. The Session ID indicates:
the identity of the analyst
the database to which the analyst is logged in
the duration for which the analyst has been logged into that database.
The API provides a LogIn transaction to generate a valid Session ID for a given analyst – regular license count, concurrent session and session timeout restrictions all apply to this session. This Session ID is then passed as an argument to all other transactions to authenticate the analyst. A corresponding LogOut transaction is provided to end that session. After LogOut has been called, the given Session ID is no longer valid.
Each transaction also has three optional parameters:
UserID
Password
Database
If these parameters are passed to the transaction, the web service will log the user in, execute the transaction and log the user out after the transaction is executed. In case of an error, the user will be logged out and an error will be returned.
For each transaction executed, events are inserted into the ASM Activity Log detailing the parameters passed to the transaction and the values returned by the transaction.
All transactions in the ASM web service interface require a valid SessionID to execute. This can either be generated using the LogIn transaction or by passing in the Login details to the specific transaction.
The ASM web service is installed by default for each system you create and can be found at the following URL:
http://<machinename>/<VirtualDirectory>/ServiceManager.svc
All examples in this documentation have been written using VB.NET. The following sections describe the API: how the input and output parameters are declared, parameter types and return values.
Authentication
The ASM web service uses the Login ID/Password and Session ID for authenticating logins. As it is a generic web service, it does not use the Microsoft Integrated Windows authentication mechanism, and is thus not targeted for use from only other Windows systems. Anonymous access must be used for the web services API.
If the API needs to be used with Integrated Security enabled, you must:
create a new system that points to the same ASM database
set up a password for an API analyst to enable them to log on
set the ASM System virtual directory to use anonymous access for IIS directory security.
Person records flagged as only Users cannot be used for logging on to the ASM web service. A person record flagged as Analyst in ASM Core must be used to log on to the API.
The ASM Web Service has not been designed to allow the use of NT authentication.
Input and Output Paramaters
The input and output parameters for all Classic API transactions are defined as classes. A list of all available classes is provided in Appendix H: Classes. In addition to this, a detailed explanation of the input parameters for each transaction including mandatory and default values are provided.
Each class conforms to a naming convention. All classes are named as follows:
Input Classes: | XXXRequest |
Output Classes: | XXXResponse |
Input Classes
Every input class contains certain common fields:
Session Information: sID, sUserID, sPassword, sDatabase. See the Transaction Login section for more information.
Custom parameter placeholders. See the section Define Custom Parameters for more information.
Not all fields in the input class are mandatory. The fields that are mandatory are specified for each transaction throughout this document.
If a mandatory field is not passed to an API transaction, the transaction will return an error.
Parameter Types
All fields in Request and Response classes are prefixed with a character indicating the type of that field.
Exceptions include the “Ret” field for response classes.
Prefix | Type | Additional Information |
N | Integer | |
S | String | |
A | Array | Array with each element corresponding to a parameter and value. These are only used to define Custom Parameters. See Define Custom Parameters for more information. |
l | Lookup Field | Lookup fields are used by the API to find an existing entity in ASM. For example, lCustomer could be used to lookup the User for a new call. Every lookup field can be used to search by name or ref. If the input value begins with a tilde (~), the search will be performed by ref. Otherwise, the search will be performed by name. See Appendix G: API Lookups for more information. |
b | Boolean | |
y | Yes/No | Yes/No fields are passed as strings and can contain any of the following “Y”, “N”, ”T”, ”F”, ”1”, or ”0”. |
d | Date/Time | Date fields are passed as strings with the format “YYYY-MM-DD HH:MM:SS” in 24-hour time format. |
x | Byte() | Byte array, only used in ObjectAttach Transaction. |
Output Classes
Like the input values, all return values are contained in classes.
Each output class may return:
Entity reference number
Message
API return value (warnings, errors)
Possibly result set
Entity Reference Number
Some output classes may return the reference number of an entity for certain transactions, such as create, update, etc. For example, a call number is returned in the case of the CallCreate Transaction.
Error/Warning Messages
Each return class contains a message field sMessage. The sMessage field contains any error or warning message returned from the API Transaction.
Transaction Status Codes
Each return class contains a response code field Ret. The Ret field has the type of APIReturn indicating the status of the transaction. The following status codes can be returned:
Status Code | What it means |
Zero | Transaction has been executed successfully |
>=1000 | An error occurred and the transaction could not be executed |
1-999 inclusive | Indicate a warning, which is a non-critical step in the transaction failed. However, the transaction was completed. |
A complete reference of status codes is provided in Return Values.
ResultSet
Some API transactions return results in a ResultSet object. This is a DataSet that contains rows of data.
An example of iterating through a ResultSet in VB.NET (localhost is the name of the web reference added to the project) is as follows. This assumes that there is a ResultSet returned following a CallRetrieve Transaction.
Transaction Login
Each transaction takes certain session information as part of its input.
There is the option to Login using the LogIn transaction to generate a session ID. This session ID is then passed to each transaction, and after the required API Transactions have been executed, you can call the LogOut transaction to log the analyst out of the system.
Each transaction also has three optional parameters:
UserID
Password
Database
Each transaction must be provided with either the session ID (sID) or all three of sLoginUserID, sLoginPassword and sDatabase. If these parameters are passed to the transaction, the web service will log the user in, execute the transaction and log the user out again.
Lookup Arguments
In instances where entities are linked to other entities (for example, calls to CMDB items, requests to request risk), these links are populated via a Lookup argument. Rather than pass the unique identifier of the linked entity, the transaction receives the name (or equivalent) or Ref of that entity. When the transaction is executed, the code looks up the entity by its name or Ref, and retrieves the unique identifier for that entity.
The name of an entity is ambiguous. In some cases the name does not exist, so all Lookups are performed on the unique identifier instead. These include calls, requests, and tasks.
Multi-tiered Entities
For multi-tiered entities, such as call issue Types and Request Types, Lookups are only performed against the name of the first tier entity.
Attributes enable you to specify three tiers of Type (using three separate parameters), while Knowledge transactions let you specify the knowledge type through to lower tiers.
CMDB Items transactions enable you to select CMDB Item Types down to lower tiers.
For more information about Attribute transactions, see Attribute Transactions. For more information about Knowledge transactions, see Knowledge Transactions.
Entities Representing Person Records
For entities representing people, all person records are looked up using their email address.
When more than one matching entity is found in the Lookup, the first entity found is used.
Lookup Errors
If a Lookup fails, an error or warning is generated depending on the nature of the linked entity. A failed lookup-up on a major entity generates an error. Major entities include:
Calls
Requests
Tasks
CMDB items
Users
Organizations
Locations
Contracts
External Suppliers
Analysts
IPK/Workflow Groups
Workflow Templates
Bulletin board entries
Knowledge entries
Knowledge Types
Attributes
Security Profiles
Stakeholders
All other entities are treated as warnings, and an appropriate default value is substituted.
It is possible to customize the means by which an entity is looked up by customizing the underlying query that performs the Lookup. Please contact your Alemba® Account Manager for information on how to achieve this.
Defining Custom Parameters
The API enables you to specify an unlimited number of custom parameters that are optional. These parameters allow transactions to update fields other than the standard fields defined in the transaction.
The API transactions use the same processes used within ASM to achieve certain results, for example, the API and the full application both use the query Insert Asset to create a config item.
All custom parameters to use in a transaction are stored in a Byte Array field. The naming convention for each entry in the array is CustomParamName=CustomParamValue. In other words, each entry in the array should consist of the field name to update, followed by an equals ‘=’ character, and then followed by the value of the specified field.
A client wants to update Self Service Portal Display Category and Service Portfolio Status on a Service to ‘Communications’ (reference number 3) and ‘Service Request Catalog’ (reference number 1) using the Classic API. This can be achieved by adding “PORTAL_CATEGORY=3” and “PORTFOLIO_STATUS=1” as entries into the aCustomParameters field of the input class of the CMDBItemUpdate transaction.
The same can be applied to transactions involving a client-defined custom field on a given entity as long as the client has defined that column in the entity’s standard Insert, Update and Get queries.
Using soapUI
The type of the value needs to be specified for it to work when using soapUI. Custom parameters need to be entered as below:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:emc.com:Ionix:ServiceManager:API:v9.0"> <soapenv:Header/> <soapenv:Body> <urn:CallCreateRequest> <urn:sLoginUserID>aa</urn:sLoginUserID> <urn:sLoginPassword>aa</urn:sLoginPassword> <urn:sDatabase>SQL</urn:sDatabase> <urn:sProblemDescription>Test</urn:sProblemDescription> <urn:aCustomParameters> <urn:CustomParamData xmlns:i="http://www.w3.org/2001/XMLSchema-instance"> <urn:Key>EXTFLDV_500001</urn:Key> <urn:Value i:type="a:string" xmlns:a="http://www.w3.org/2001/XMLSchema">test</urn:Value> </urn:CustomParamData> </urn:aCustomParameters> </urn:CallCreateRequest> </soapenv:Body> </soapenv:Envelope>
Using C# or vb
In these cases you need to create an array of CustomParamData and add Key Value pairs.
Here is an example of C#:
private static Infra.API.ServiceContracts.ExecuteQueryTableResponse ExecuteQuery(Infra.API.ServiceImplementation.ServiceManager InfraAPI, String APISessionID, string queryName, List<KeyValuePair<string, string>> parameters) { if (queryName == "") return null; Infra.API.ServiceContracts.ExecuteQueryRequest APIExecuteQueryRequest = new Infra.API.ServiceContracts.ExecuteQueryRequest(); APIExecuteQueryRequest.sID = APISessionID; APIExecuteQueryRequest.sQueryName = queryName; //Add custom parameters Infra.API.DataContracts.CustomParamData[] CustomParams = new Infra.API.DataContracts.CustomParamData[parameters.Count]; for (int i = 0; i < parameters.Count; i++) { CustomParams[i] = new Infra.API.DataContracts.CustomParamData(); CustomParams[i].Key = parameters[i].Key; CustomParams[i].Value = parameters[i].Value; } APIExecuteQueryRequest.aCustomParameters = CustomParams;
return InfraAPI.ExecuteQuery(APIExecuteQueryRequest); }
Updating Extension Fields
You can use the CustomParameters array to update extension fields that have been added to a call, request, task or CMDB item screen set. To do this, find the FIELD_REF of the required extension field using the SU_FIELD table (in other words, do not use the NAME). The custom parameter name then becomes ‘EXTFLDV_<field_ref>’.
For example, a client has created an extension field Website Ref (name WEBSITE_REF) to store the website reference and wants to use the CMDBItemUpdate transaction to update this extension field on a CMDB item. This can be achieved by searching for FIELD_REF from the SU_FIELD table, where NAME=WEBSITE_REF. If the FIELD_REF returns a value ‘500061’, the client can enter “EXTFLDV_500061=www.alemba.com” as an entry into the aCustomParameters array of the input class of the CMDBItemUpdate transaction.
Patterns
Most entities follow a general pattern. For each entity, the following transactions can be defined:
Create
Update
Delete
Retrieve
The output classes of the Create transaction comprises a field that returns the unique identifier of the created entity, which can be passed to the Update, Delete and Retrieve transactions. The Retrieve transactions have a Details out argument, which is a Recordset object containing the entity’s properties.
Create, Update, Retrieve, and Delete transactions are limited by the following rules:
Requests can only be created from workflow templates.
Tasks cannot be created individually, but are generated when requests are created.
Calls, requests, and tasks support a Forward transaction as an alternative update transaction.
Calls, Tasks and Requests cannot be deleted as such and include a Close transaction instead
Entities with a distinguishable name, such as Bulletin Entries, Knowledge Entries, all CMDB items, can be retrieved using that name or the unique identifier.
Person transactions are limited to User records only.
History Records
Some API transactions such as call forward and timesheet transactions allow history records to be entered.
This follows the same transactions as the main application. The start and end dates represent the start and end times of the action. There is also an option to use security profiles if this is enabled on your system.
Auditing
All the transactions that make changes to entities in the database (create, delete, update) have a Reason parameter. If the Audit Trail is enabled, this parameter takes a string that is saved to the Audit Trail for that particular item (call, request, task, CMDB item) as the reason for the change. The API will always update the last update date and last updated by fields even when the audit trail is not enabled.