API and Data Import for Requests
There is an API and a data import facility for importing and submitting requests.
Using the API
The standard PPM Pro methods for creating and updating entities supports requests (ID=307). In addition, there is a new API call for submitting requests: performGatedEntityAction, which currently supports the Submit action. See the table below for the list of APU methods.
Use the Admin/Web Services API page to find the fields defined for the request entity (both UDFs and standard fields) by selecting the Request entity and then clicking the View Fields button. Pick the tab for the type of call (Select/Insert/Update) and locate the fields and their IDs. Note the Is Required column, and be sure to include value pairs for those fields as necessary.
API | Notes |
---|---|
selectEntity |
Requires an entity ID. Returns core set of metadata (not all metadata) for specified entity. If you want specific metadata, must have a Request ID for each field you want returned. Best practice is to always specify what fields you want returned. |
findEntity |
Use the request entity type ID = 307. Returns all requests if no value pair(s) included. |
insertEntity |
Mandatory fields must be included (fields required for saving); required fields (fields required for submitting) are optional. |
updateEntity | Same as insertEntity. |
deleteEntity | Requests cannot be deleted if they are In Progress or On Hold. |
performGatedEntityAction |
Currently supports Submit action. All fields that are required for Submit must be included. Requires a session id, entity type (307), action (submit only supported), list of one or more entity ID’s to perform action on. If submitting multiple requests with one call, if one or more fails, they all fail. When viewing the Activity Log, the name associated with API user is the "Performed By" value |
Data Import
Use the Generate Import File button to generate an Excel template that you can use to import the data for creating and submitting (New) or updating (Update) requests. Once you fill out the spreadsheet and save, you select the entity data type to import from the list and click the Import button, following the instructions for mapping fields (including UDFs) and importing the data. For more information, see About Data Import.
Request Import Notes
- Requests require a Category ID. This ID can be found using the ID Inspector on Admin/Setup/Requests/Categories
- Title, Category ID and Requester (in the form of Last, First) are system required fields on all requests.
- Date format is mm/dd/yyyy
- To configure a template for importing and submitting a request, use the Generate Import File for New template and check the Submit Intake Request on Create check box in the wizard that appears after you click Import.
- When creating an Excel template for creating requests, the process is different depending on whether or not your import is configured to submit the requests:
- No submit - If not submitting the new requests, minimally include valid values for ALL fields marked Required in Available Fields (standard and UDF). Only fields included in the Details for the category will appear on the request. Best practice is to make fields required at the Details level only.
- Submitting - If submitting the new requests (you plan to check the checkbox next to "Submit Intake Requests on Create" on the first step of the wizard), in addition to minimally including valid values for ALL fields marked Required in Available Fields (standard and UDF), you must also include valid values for any required fields at the Category level. Note that the fields required for each category may differ, as a result they are not shown in the import field with an asterisk - you'll have to check the category's Details screen in SSA to determine which fields are required for submission on New.