Adding a New API Job

Complete the following steps to add a new API job on the API Jobs page.

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

Configuring the Params Tab

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

Configuring the Headers Tab

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.

Configuring the Body Tab

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” }

Enabling the Bearer Token

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 

Enabling Paging Information

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:

Page
PageSize
Star
End
Offset
Limit
TotalPages
TotalRecords
Next
Token

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:

QueryString is selected for passing the paging parameter in the URL query string.
Body is selected to pass the paging parameter in the body.
Response is selected to map the value from the result of the API to the total pages and total records.

Action

Clicking the Delete link in the Action field deletes a row in the Paging Info tab.

Testing the Connection

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