Adding a New API Job
Important:You must add at least one API job to populate the table on the API Jobs page.
To add a new API job:
1. | Go to the API Jobs page (API Jobs > API Jobs). |
2. | Select the Jobs Scheduled tab. |
3. | Click the Add New API Job button, which opens the Add API Jobs dialog box. The following table describes the Add API Jobs functions. |
Function |
Description |
Refresh |
Refreshes the list of available SaaS applications for the associated Organization ID. |
Pause |
Temporarily stops the execution of the scheduled job. |
Clear |
Clears all the fields. |
Enable Paging |
For details, see Enabling Paging Information. |
Test Connection |
For details, see Testing the Connection. |
Next |
Enables you to go from the Params tab to the Headers tab and then to the Body tab. |
Cancel |
Cancels the API job configuration. |
4. | Complete the Add API Job fields. For details, see the following table. |
Field |
Description |
Job Name |
Enter the appropriate name in the Job Name field. |
Application |
Select the appropriate SaaS application name from the associated Organization ID’s prepopulated dropdown menu. |
Task |
Select the appropriate Flexera SaaS Management integration task to associate with the SaaS application usage data to be transferred to FSM Data Ingestion Utility. For Task descriptions, see the “Tasks to Load Data” section in SaaS Data Payload. Note:To enable the discoveredAppUsage task, you first need to add the CASB managed application in SaaS Management. For more information, see Adding an Application. You need to uncheck the Direct integrations only checkbox to search for the CASB - by Shadow IT managed application. |
Schedule |
Select the appropriate frequency (Daily, Weekly, Monthly) and time (hour, minutes, AM/PM) to run the scheduled API job. For Weekly scheduled jobs, select the appropriate day of the week. For Monthly scheduled jobs, select the appropriate day of the month. The time is displayed per your local time. |
Pause |
Selecting the Pause checkbox temporarily stops the execution of the scheduled job. |
Method |
Select either GET or POST. |
API URL |
Enter the appropriate API URL to ingest the SaaS data. |
5. | The Add API Job page has two phases: Request Info and Metadata Mapping. Complete the following Request Info tasks before Metadata Mapping for API Jobs. |
• | Configuring the Params Tab |
• | Configuring the Headers Tab |
• | Configuring the Body Tab |
• | Enabling the Bearer Token |
• | Enabling Paging Information |
• | Testing the Connection |
The parameter configured within the Params tab is passed in the API URL as part of the query string.
The following table describes how to configure the fields in the Params tab.
Field |
Description |
System Key |
The fromDate and toDate functions filter the data between the dates. These values cannot be deleted or updated since these keys are system keys. You cannot add other keys, but you can add a Mapped Field. |
Mapped Field |
This key is for response mapping with the fromDate and toDate functions. These values are completely optional. You can also map your own parameters to be passed in the API URL query string or header parameters. |
Value |
The format of the fromDate and toDate key values need to be entered in the date format that is acceptable to the API. Other values, such as text or numbers, can be in any other format as required to be passed in the API call. Note:For scheduled and manually run API jobs, the fromDate parameter in an API call is used to filter SaaS user activity data. This fromDate parameter enables you to retrieve user activity events starting from a designated date and time. As a result, only relevant and up-to-date SaaS vendor information is integrated into your managed SaaS applications with SaaS Management. For further details, see Retrieving SaaS User Activity Data Using the FromDate and MappedField Parameters. |
Action |
These key values cannot be deleted because these keys are system keys. |
Retrieving SaaS User Activity Data Using the FromDate and MappedField Parameters
The following table explains the possible scenarios for how the fromDate and the mappedField parameters affect the retrieved SaaS user activity data.
Is the FromDate Parameter Available in the Value Field? |
Is the MappedField Parameter Available in the Value Field? |
Is the Last Successful Run Date Available to the API Job? |
Which SaaS User Activity Data Will I See? |
Yes |
Yes |
No |
Between the fromDate and the system date |
Yes |
Yes |
Yes |
Between the last successful run date and the system date |
No |
Yes |
Yes |
Between the last successful run date and the system date |
No |
Yes |
No |
All SaaS user activity data |
Headers can be configured to provide authorization, authentication, content type, origin, and more. These parameters are passed as a header in the client request.
The following table describes how to configure fields in the Headers tab.
Field |
Description |
Key |
Enter the header parameter in this field. Example: Enter Authorization for authenticating the API. |
Value |
Values in this field can be related to a key. Example: Enter the authorization token for a bearer token or a basic token. |
Action |
Clicking the Delete link in the Action field does not delete the values in the Value field. |
The Body tab is configured for the POST API. In the Body tab, go to the text box and enter the POST API in the JSON format where the property and its value can be assigned. Example: { “createdDate”: “2022-12-01”, “name”:”josef” }
As an option, you can enable a bearer token for API jobs. This feature works by selecting the Default or the Advanced installation option in Installing FSM Data Ingestion Utility. Select Advanced to run FSM Data Ingestion Utility as a Windows Service and to schedule API tasks. The following links detail the process for enabling the bearer token.
• | Enabling Advanced AUTH Information for a New API Job |
• | Enabling Advanced AUTH Information for an Existing API Job |
• | Supported OAuth Methods in FSM Data Ingestion Utility |
• | Common Attributes Information in JSON Templates for All Supported OAuth Methods |
• | Client Secret Based Authentication |
• | Client User Based Authentication |
• | Refresh Token Based Authentication |
Enabling Advanced AUTH Information for a New API Job
The following steps are required to enable advanced AUTH information for a new API job. For details, see the following screenshot.
To enable advanced AUTH information for a new API job:
1. | Go to the API Jobs page (API Jobs > API Jobs). |
2. | Select the Request Info phase. |
3. | Go to the Advanced Auth Info tab. |
4. | Select the Advanced Auth checkbox, located to the left of the Pagination checkbox, to enable the field for configuring JSON data as per the appropriate OAuth method. |
Enabling Advanced AUTH Information for an Existing API Job
The following steps are required to enable advanced AUTH information for an existing API job. For details, see the following screenshot.
To enable advanced AUTH information for an existing API job:
1. | Go to the API Jobs page (API Jobs > API Jobs). |
2. | Select the Request Info phase. |
3. | Go to the Headers tab. |
4. | In the Action column, click Delete to delete the existing Authorization header information. |
5. | Go to the Advanced Auth Info tab and select the Advanced Auth checkbox to enable the field for configuring JSON data as per the appropriate OAuth method. |
Supported OAuth Methods in FSM Data Ingestion Utility
FSM Data Ingestion Utility currently supports the following OAuth methods. Before you begin, see the Common Attributes Information in JSON Templates for All Supported OAuth Methods. Then click the appropriate OAuth method link for more details.
• | Client Secret Based Authentication |
• | Client User Based Authentication |
• | Refresh Token Based Authentication |
• | Auth Token Based Authentication |
Common Attributes Information in JSON Templates for All Supported OAuth Methods
The following common attributes information in JSON templates are applicable for all supported OAuth methods in FSM Data Ingestion Utility.
• | "token_expiry_in_minutes" is an optional field. If a minutes value is not entered, the default time to generate the token will be 5 minutes. This configurable value is stored in the Settings table. If a minutes value is entered, the entered value will take priority over the default value of 5 minutes in the Settings table. |
• | "form-data" displays by default when you do not enter a value for "headers": { "Content-Type": } |
• | "token_url" : "Token URL value", is a required field to generate the access token. The token URL value is specific to the application. |
Client Secret Based Authentication
The following sample template is for the JSON "body" section using client secret based authentication.
Note:The following JSON fields are required for client secret based authentication:
• | "auth_type" |
• | "token_url" |
• | "body" section fields "grant_type", "client_id", and "client_secret" |
{
"auth_type" : "ClientSecretAuthentication",
"token_url" : "Token URL value",
"token_expiry_in_minutes" : "Specify the time in minutes to after which new access token needs to be generated",
"headers": {
"Content-Type": "form-data"
},
"body": {
"scope": "scope value",
"grant_type" : "client_credentials",
"client_id" : "Client ID value",
"client_secret": "Client Secret Value"
}
}
Client Secret Based Authentication Error Message
If any of the mandatory fields are missing in the JSON "body" section, an error message mentioning the missing parameters will display after clicking the Test Connection button in the Advanced Auth Info tab.
Below is a sample error message.
Please provide valid Advanced Auth information.
client_id is required under body
client_secret is required under body
Client User Based Authentication
The following sample template is for the JSON "body" section using client user based authentication.
Note:The following JSON fields are required for client user based authentication:
• | "auth_type" |
• | "token_url" |
• | "body" section fields "grant_type", "client_user", and "client_password" |
{
"auth_type" : "ClientUserAuthentication",
"token_url" : "Token URL value",
"token_expiry_in_minutes": "Specify the time in minutes to after which new access token needs to be generated",
"headers": {
"Content-Type": "form-data"
},
"body": {
"grant_type" : "client_credentials",
"scope": "scope value",
"client_user": "Client User value",
"client_password": "Client Password value"
}
}
Client User Based Authentication Error Message
If any of the mandatory fields are missing in the JSON "body" section, an error message mentioning the missing parameters will display after clicking the Test Connection button in the Advanced Auth Info tab.
Below is a sample error message.
Please provide valid Advanced Auth information.
client_user is required under body
client_password is required under body
grant_type is required under body
Refresh Token Based Authentication
The following sample template is for the JSON "body" section using refresh token based authentication.
Note:The following JSON fields are required for refresh token based authentication:
• | "token_url" |
• | "auth_type" |
• | "body" section fields "grant_type" and "refresh_token" |
{
"token_url": "Token URL value",
"auth_type": "RefreshTokenAuthentication",
"token_expiry_in_minutes": "10",
"headers": {
"Content-Type": "application/x-www-form-urlencoded"
},
"body": {
"grant_type": "refresh_token",
"client_id": "",
"client_secret": "",
"refresh_token": "Refresh Token value"
}
}
Refresh Token Based Authentication Error Message
If any of the mandatory fields are missing in the JSON "body" section, an error message mentioning the missing parameters will display after clicking the Test Connection button in the Advanced Auth Info tab.
Below is a sample error message.
Please provide valid Advanced Auth information.
refresh_token is required under body
Auth Token Based Authentication
The following sample template is for the JSON "body" section using auth token based authentication.
Note:The following JSON fields are required for auth token based authentication:
• | "auth_type" |
• | "auth_url" |
• | "token_url" |
• | "body" section fields "client_id", "client_secret", and "redirect_uri" |
{
"auth_type": "AuthTokenAuthentication",
"auth_url": "Authentication URL Value",
"token_url": "Token URL Value",
"token_expiry_in_minutes": "Specify the time in minutes to after which new access token needs to be generated",
"headers": {
"Content-Type": "application/x-www-form-urlencoded"
},
"body": {
"scope": "Scope Value",
"client_id": "Client Id Value",
"client_secret": "Client Secret Value",
"redirect_uri": "Redirect URI Value"
}
}
Auth Token Based Authentication Error Message
If any of the mandatory fields are missing in the JSON "body" section, an error message mentioning the missing parameters will display after clicking the Test Connection button in the Advanced Auth Info tab.
Below is a sample error message.
Please provide valid Advanced Auth information.
client_id is required under body
client_secret is required under the body
redirect_uri is required under the body
Paging information is the separate sections from params to configure the full or delta load of the task selected. It has predefined parameter keys to select and those are mapped to the URL, body, or response keys.
Best Practice:If a single API call response size is more than 10MB, then it should be configured with pagination.
If required, complete the following steps to enable paging information.
To enable paging information:
1. | Go to the API Jobs page (API Jobs > API Jobs). |
2. | Select the Request Info phase. |
3. | Go to the Params tab. |
4. | Select the Enable Paging checkbox on the far right of the screen to enable the Paging Info tab. |
5. | Go to the Paging Info tab. |
6. | Refer to the following table to configure the fields in the Paging Info tab. |
Field |
Description |
||||||||||||||||||||||||||||||
Key |
The system key is used to process pagination with different options in API configuration. From the dropdown menu, select the appropriate predefined key:
|
||||||||||||||||||||||||||||||
Mapped Key |
This key is to be mapped as a part of the actual URL query string, request body for the POST API, or the result on executing the API. |
||||||||||||||||||||||||||||||
Value |
This field is optional. If you enter the value, it considers this value prior to the result of the API. |
||||||||||||||||||||||||||||||
Parameter Type |
From the dropdown menu, select the appropriate predefined parameter:
|
||||||||||||||||||||||||||||||
Action |
Clicking the Delete link in the Action field deletes a row in the Paging Info tab. |
After completing all the required fields in the Params, Headers, and Body tabs of the Add API Job page, you can test the API connection. Clicking the Test Connection button on the bottom left of the screen executes an API and checks whether or not there is an API response.
The following table describes the possible API Test Connection messages.
Test Connection Message |
Description |
200 - OK - Test Connection Succeeded |
Successful Test connection |
401 - Unauthorized - Test Connection failed |
Authorization is incorrect/not provided |
503 - Service Unavailable - Test Connection failed |
The API is not ready to process requests. |
500 - Internal Server Error - Test connection failed |
There is an error in getting a response for the configured API. There is something wrong with the original API to execute. |
1000 - Internal Error - Test connection failed |
Unable to execute API with the provided configuration |