Managing Schedule Types and Metadata (REST API)

Modified on Wed, 15 Jul at 4:14 PM

This guide covers managing schedule types and metadata fields through the ILAP Analytics REST API — listing, creating, updating, and upserting field values. It is intended for developers and integrators configuring ILAP Analytics, and assumes you have a bearer token or service token with the required role for each endpoint.

Authorization

Provide your token in the Authorization header, either as a bearer token or a service token:

Authorization: Bearer <token>

Authorization: IlapAnalyticsToken <service_token>

Base URL in the examples below is https://app-ilapanalytics-api-dev.azurewebsites.net; substitute your own environment's base URL.

Schedule Type

Endpoints

Get All Schedule Types
Get All Schedule Types with Metadata Fields
Get Single Schedule Type with Metadata Fields
Update Schedule Type
- Upsert Schedule and Activity Fields

Get All Schedule Types

Overview

List all Report Schedule Types available in the system. This lightweight endpoint returns only minimal data about each schedule type.

Endpoint

Method: GET
URL: /api/ReportScheduleTypes

Required Permission

DataReader

Request Parameters

Headers

Authorization: Bearer <token> | IlapAnalyticsToken <service_token>

Usage

List Schedule Types with Minimal Data

Request

curl --location 'https://app-ilapanalytics-api-dev.azurewebsites.net/api/ReportScheduleTypes' \
--header 'accept: application/json' \
--header 'Authorization: IlapAnalyticsToken <service_token>'

Response

[
  {
    "planningLevel": 4,
    "planningLevelText": "Level 4",
    "title": "Example Schedule Type 1",
    "lastModified": "2024-06-20T07:52:24.5766667Z",
    "lastModifierId": 1,
    "lastModifierName": "Tanvir Ahmed",
    "id": 7,
    "created": "2024-06-20T07:52:24.5766667Z"
  },
  {
    "planningLevel": 3,
    "planningLevelText": "Level 3",
    "title": "Example Schedule Type 2",
    "lastModified": "2024-11-01T13:03:13.7337221Z",
    "lastModifierId": 1,
    "lastModifierName": "Sam H",
    "id": 8,
    "created": "2024-06-20T10:28:25.3033333Z"
  },
  {
    "planningLevel": 6,
    "planningLevelText": "Level 6",
    "title": "Example Schedule Type 3",
    "lastModified": "2024-11-07T06:20:51.9282697Z",
    "lastModifierId": 1,
    "lastModifierName": "John Doe",
    "id": 9,
    "created": "2024-06-21T04:46:39.3733333Z"
  }
]

Get All Schedule Types with Metadata Fields

Overview

List all Report Schedule Types available in the system. This endpoint provides complete data for each Schedule Type, including its Metadata Fields.

The usedBy property of each metadata field indicates what planning object type it can be used for.
The type property indicates its data type according to the System.TypeCode enum.

Optionally, you can also include the Metadata Field Values.

The value property of each Field Value contains the value.
The stringValue property is populated with the value if the data type is string. If the type is numeric, boolean, or dateTime, the numericValue, booleanValue, or dateTimeValue properties would be populated respectively.

Endpoint

Method: GET
URL: /api/ReportScheduleType

Required Permission

DataReader

Request Parameters

Headers

Authorization: Bearer <token> | IlapAnalyticsToken <service_token>

Query Parameters

includeMetaDataFieldValues (optional)
- Type: boolean
- Description: A flag to indicate whether to load the metadata field values.
- Default: true (load all field values)

Usage

List all Schedule Types with Metadata Fields and Field Values

Use query parameter includeMetaDataFieldValues=true or do not use it at all to load all metadata field values.

Request

curl --location 'https://app-ilapanalytics-api-dev.azurewebsites.net/api/ReportScheduleType' \
--header 'accept: application/json' \
--header 'Authorization: IlapAnalyticsToken <token>'

Response

[
  {
    "planningLevel": 1,
    "planningLevelText": "Level 1",
    "title": "Example Schedule Type 1",
    "receivedFromSchedule": false,
    "reportSchedules": [],
    "metadataFields": [
      {
        "ilapId": "R-72ef6abf-4b66-4070-ac1e-64cfb41136c6",
        "isVisible": true,
        "name": "Act_Phase",
        "description": "Phase code (identification is solved in a different way)",
        "receivedFromSchedule": true,
        "validationRequirement": 2,
        "validationRequirementText": "ValueInListOrBlank",
        "planningObjectTypes": 8,
        "type": 18,
        "iri": "http://ilap.org/community/oilandgas/R-72ef6abf-4b66-4070-ac1e-64cfb41136c6",
        "metadataFieldValues": [
          {
            "metadataFieldId": 2,
            "name": "Act_Phase",
            "type": 18,
            "value": "P12",
            "stringValue": "P12",
            "lastModified": "2024-11-07T11:51:27.98Z",
            "id": 202185,
            "created": "2024-11-07T11:51:27.98Z"
          },
          {
            "metadataFieldId": 2,
            "name": "Act_Phase",
            "type": 18,
            "value": "P1",
            "stringValue": "P1",
            "lastModified": "2024-11-07T11:51:27.98Z",
            "id": 202188,
            "created": "2024-11-07T11:51:27.98Z"
          }
        ],
        "usedBy": "Activity",
        "id": 2,
        "created": "2024-05-31T12:35:45.4566667Z",
        "lastModified": "2025-01-21T12:10:48.9447556Z",
        "lastModifierId": 1,
        "lastModifierName": "Jane Doe"
      }
    ],
    "creatorId": 1,
    "creatorName": "John Doe",
    "lastModified": "2024-11-27T09:24:00.0966667Z",
    "lastModifierId": 1,
    "lastModifierName": "John Doe",
    "id": 17020,
    "created": "2024-11-27T09:24:00.0966667Z"
  }
]

List all Schedule Types with Metadata Fields but not Field Values

Use query parameter includeMetaDataFieldValues=false to skip loading the Field Values.

Request

curl --location 'https://app-ilapanalytics-api-dev.azurewebsites.net/api/ReportScheduleType?includeMetaDataFieldValues=false' \
--header 'accept: application/json' \
--header 'Authorization: IlapAnalyticsToken <token>'

In the response, each metadata field's metadataFieldValues array is returned empty ([]).

Get Single Schedule Type with Metadata Fields

Overview

Retrieve a single Report Schedule Type with its Metadata Fields.

The usedBy property of each metadata field indicates what planning object type it can be used for.
The type property indicates its data type according to the System.TypeCode enum.

The field values for each metadata field are also loaded.

The value property contains the field value.
The stringValue property is populated with the value if the data type is string. If the type is numeric, boolean, or dateTime, the numericValue, booleanValue, or dateTimeValue properties would be populated respectively.

Endpoint

Method: GET
URL: /api/ReportScheduleType/{id}

Required Permission

DataReader

Request Parameters

Headers

Authorization: Bearer <token> | IlapAnalyticsToken <service_token>

Path Parameters

{id} (required)
- Type: integer
- Description: Id of the report schedule type to be retrieved

Query Parameters

planningObjectTypes (optional)
- Type: string
- Description: A comma-separated list of planning object types for which you want to load metadata fields.
- Default: If not provided, metadata fields for all planning object types will be loaded.

Usage

Get a single Schedule Type with Metadata Fields of All Planning Object Types

Do not provide the query parameter to load metadata fields of all planning object types.

curl --location 'https://app-ilapanalytics-api-dev.azurewebsites.net/api/ReportScheduleType/{id}' \
--header 'accept: application/json' \
--header 'Authorization: IlapAnalyticsToken <service_token>'

Get a single Schedule Type with only Schedule Fields

Use query parameter planningObjectTypes=schedule.

curl --location 'https://app-ilapanalytics-api-dev.azurewebsites.net/api/ReportScheduleType/{id}?planningObjectTypes=schedule' \
--header 'accept: application/json' \
--header 'Authorization: IlapAnalyticsToken <service_token>'

Get a single Schedule Type with only Activity Fields

Use query parameter planningObjectTypes=activity.

curl --location 'https://app-ilapanalytics-api-dev.azurewebsites.net/api/ReportScheduleType/1?planningObjectTypes=activity' \
--header 'accept: application/json' \
--header 'Authorization: IlapAnalyticsToken <service_token>'

Get a single Schedule Type with Schedule and Activity Fields

Provide comma-separated planning object type names in the query parameter: planningObjectTypes=schedule,activity.

curl --location 'https://app-ilapanalytics-api-dev.azurewebsites.net/api/ReportScheduleType/1?planningObjectTypes=schedule%2Cactivity' \
--header 'accept: application/json' \
--header 'Authorization: IlapAnalyticsToken <service_token>'

Upsert Schedule and Activity Fields

You can add, remove, or update the list of metadata fields for a schedule type in the same Update Schedule Type request.

This is how it works:

If you provide a metadata field that did not already exist in the schedule type, it will be added.
If you do not provide a metadata field in the request, but it existed in the schedule type, it will be deleted.
If you provided modified data (e.g., validation requirement) for a metadata field in the list, it will be updated.

This approach ensures that the schedule type will have exactly the metadata fields that you provided in the request.

Notable Properties

receivedFromSchedule: boolean. Indicates whether the value of this metadata field is received from the imported ILAP Schedule. If the flag is false, it means that the value will be manually provided by the user.
validationRequirement: number. There are 4 available content control or validation options. One of them must be provided for every metadata field added to the schedule type.
1. 0 (None)
2. 1 (Value-in-List)
3. 2 (Value-in-List or Blank)
4. 3 (Non-Blank Value)

Note

The actual Metadata Fields in the system do not get affected by these operations. They only modify the link between the metadata fields and the schedule type.

Usage

Add 1 Schedule Field and 1 Activity Field to a Schedule Type

In this request, we are adding one metadata field with id 16 (a Schedule Field) and another with id 14 (an Activity Field).

{
  "title": "Test Schedule Type",
  "description": "Test description",
  "planningLevel": 1,
  "reportScheduleTypeMetadataFields": [
    {
      "reportScheduleTypeId": 17021,
      "metadataFieldId": 16,
      "validationRequirement": 0,
      "receivedFromSchedule": true
    },
    {
      "reportScheduleTypeId": 17021,
      "metadataFieldId": 14,
      "validationRequirement": 3,
      "receivedFromSchedule": true
    }
  ]
}

Modify Properties of the Metadata Fields in the Schedule Type

Change the receivedFromSchedule property to false for the metadata field with id 16, and change the validationRequirement property to 2 for the metadata field with id 14.

{
  "title": "Test Schedule Type",
  "description": "Test description",
  "planningLevel": 1,
  "reportScheduleTypeMetadataFields": [
    {
      "reportScheduleTypeId": 17021,
      "metadataFieldId": 16,
      "validationRequirement": 0,
      "receivedFromSchedule": false
    },
    {
      "reportScheduleTypeId": 17021,
      "metadataFieldId": 14,
      "validationRequirement": 2,
      "receivedFromSchedule": true
    }
  ]
}

Remove a Metadata Field from the Schedule Type

In this request, we are sending only the field with id 14. This will result in the deletion of the metadata field with id 16 from the schedule type. Note that the original Metadata Field will still exist in the system. Only its link with the schedule type will be removed. You can add it again later.

{
  "title": "Test Schedule Type",
  "description": "Test description",
  "planningLevel": 1,
  "reportScheduleTypeMetadataFields": [
    {
      "reportScheduleTypeId": 17021,
      "metadataFieldId": 14,
      "validationRequirement": 2,
      "receivedFromSchedule": true
    }
  ]
}

Metadata Field

Endpoints

Get All Metadata Fields
Get All Metadata Fields with Usage
Get Single Metadata Field with Values
Create New Metadata Field
Update Metadata Field
- Upsert Metadata Field Values

Get All Metadata Fields

Overview

List all Metadata Fields available in the system. This lightweight endpoint returns only minimal data about each metadata field.

Endpoint

Method: GET
URL: /api/MetadataFields

Required Permission

DataReader

Request Parameters

Headers

Authorization: Bearer <token> | IlapAnalyticsToken <service_token>

Usage

Request

curl -X 'GET' \
  'https://app-ilapanalytics-api-dev.azurewebsites.net/api/MetadataFields' \
  -H 'accept: application/json' \
  -H 'Authorization: IlapAnalyticsToken <service_token>'

Response

[
  {
    "ilapId": "R-72ef6abf-4b66-4070-ac1e-64cfb41136c6",
    "name": "Act_Phase",
    "description": "Phase code (identification is solved in a different way)",
    "type": 18,
    "planningObjectTypes": 8,
    "id": 2,
    "created": "2024-05-31T12:35:45.4566667Z"
  },
  {
    "ilapId": "R-8623eacc-146c-4b7b-a7d9-c2d44f5d04ae",
    "name": "Proj_ContractId",
    "description": "Contract identifier associated with the project",
    "type": 18,
    "planningObjectTypes": 8,
    "id": 3,
    "created": "2024-05-31T12:35:45.4566667Z"
  }
]

Get All Metadata Fields with Usage

Overview

List complete data of all Metadata Fields available in the system and optionally include the usage information.

Endpoint

Method: GET
URL: /api/MetadataField

Required Permission

DataReader

Request Parameters

Headers

Authorization: Bearer <token> | IlapAnalyticsToken <service_token>

Query Parameters

includeUsage (optional)
- Type: boolean
- Description: A flag to indicate whether to load the usage data:
  1. Usage count (timesInUse)
  2. Value count (numberOfValues)
  3. Value list (metadataFieldValues[])
- Default: false

Usage

List Metadata Fields with Usage

curl -X 'GET' \
  'https://app-ilapanalytics-api-dev.azurewebsites.net/api/MetadataField' \
  -H 'accept: application/json' \
  -H 'Authorization: IlapAnalyticsToken <service_token>'

List Metadata Fields without Usage

Use query parameter includeUsage=false to skip usage count for each metadata field.

curl -X 'GET' \
  'https://app-ilapanalytics-api-dev.azurewebsites.net/api/MetadataField?includeUsage=false' \
  -H 'accept: application/json' \
  -H 'Authorization: IlapAnalyticsToken <service_token>'

Get Single Metadata Field with Values

Overview

Get a single metadata field with values.

The timesInUse property indicates how many times this field was used in imports.
The numberOfValues property indicates how many distinct values it received during imports.

Endpoint

Method: GET
URL: /api/MetadataField/{id}

Required Permission

DataReader

Request Parameters

Headers

Authorization: Bearer <token> | IlapAnalyticsToken <service_token>

Path Parameters

{id} (required)
- Type: integer
- Description: Id of the metadata field to be retrieved

Usage

curl -X 'GET' \
  'https://app-ilapanalytics-api-dev.azurewebsites.net/api/MetadataField/5' \
  -H 'accept: application/json' \
  -H 'Authorization: IlapAnalyticsToken <service_token>'

Create New Metadata Field

Overview

Create a new Metadata Field in the System. Some of the important data you have to provide:

name: string. Must be unique in the system. Must start with a letter and can only contain alphanumeric characters and underscores.
ilapId: string. Must be unique in the system. The format is R-{GUID}.
planningObjectType: number. To create a schedule field, use 2; for an activity field, use 8.
type: number. Data type according to the System.TypeCode enum. The following types are supported:
1. 18 (string)
2. 14 (numeric)
3. 3 (boolean)
4. 16 (datetime)

Endpoint

Method: POST
URL: /api/MetadataField

Required Permission

Administrator

Request Parameters

Headers

Authorization: Bearer <token> | IlapAnalyticsToken <service_token>

Usage

Create a Schedule Field with Data Type String and Values

We can add a list of values (code, description) if the data type is string.

{
  "name": "ExampleField_1",
  "description": "Example field description",
  "ilapId": "R-4492d79c-5f1b-4008-9e69-b9112290a786",
  "iri": "",
  "isVisible": true,
  "metadataFieldValues": [
    {
      "stringValue": "TestValue2",
      "description": "Value Description 2",
      "type": 18
    },
    {
      "stringValue": "TestValue1",
      "description": "Value Description 1",
      "type": 18
    }
  ],
  "planningObjectTypes": 2,
  "type": 18
}

Create an Activity Field with Data Type Numeric

We do not manually add values when the data type is not string. But values can be received by importing ILAP files.

{
  "name": "ExampleField_11",
  "description": "Example field description",
  "ilapId": "R-4492d79c-5f3b-4008-9e69-b9112290a786",
  "iri": "",
  "isVisible": true,
  "planningObjectTypes": 8,
  "type": 14
}

Upsert Metadata Field Values

You can add, remove, or update the field values in the same Update Metadata Field request.

This is how it works:

If you provide a field value in the request that did not exist in the metadata field, it will be added.
If you do not provide a field value in the request, but it existed in the metadata field before, it will be deleted.
If you provide a modified value code and/or description of any field value in the request that existed in the metadata field before, it will be updated.

This approach ensures that the metadata field will have exactly the field values that you provided in the request.

Usage

Add 2 field values to a Metadata Field

We are providing the value code in the stringValue property and description in the description property. The data type is 18 (string).

{
  "name": "Example_Metadata_Field",
  "description": "",
  "ilapId": "R-4492d79c-5f1b-4008-9e69-b9213290a886",
  "iri": "",
  "isVisible": true,
  "planningObjectTypes": 2,
  "type": 18,
  "metadataFieldValues": [
    {
      "metadataFieldId": 33124,
      "stringValue": "NewValue_2",
      "description": "Description 2",
      "type": 18
    },
    {
      "metadataFieldId": 33124,
      "stringValue": "NewValue_1",
      "description": "Description 1",
      "type": 18
    }
  ]
}

Modify the descriptions of both field values

When modifying an existing field value description, provide the field value ids.

{
  "name": "Example_Metadata_Field",
  "description": "",
  "ilapId": "R-4492d79c-5f1b-4008-9e69-b9213290a886",
  "iri": "",
  "isVisible": true,
  "planningObjectTypes": 2,
  "type": 18,
  "metadataFieldValues": [
    {
      "id": 203228,
      "metadataFieldId": 33124,
      "stringValue": "NewValue_2",
      "description": "Description 2 Modified",
      "type": 18
    },
    {
      "id": 203229,
      "metadataFieldId": 33124,
      "stringValue": "NewValue_1",
      "description": "Description 1 Modified",
      "type": 18
    }
  ]
}

Modify the value codes of both field values

Value code update is not supported directly, so we leverage the power of the upsert operation here. When the id properties are not provided, the system treats the field values as new entries. Consequently, it removes the existing field values whose ids are not included in the provided list and adds the new values. For the field values where we want to update the value codes, we simply remove their ids from the request. This way, the old field values are replaced with the new ones.

{
  "name": "Example_Metadata_Field",
  "description": "",
  "ilapId": "R-4492d79c-5f1b-4008-9e69-b9213290a886",
  "iri": "",
  "isVisible": true,
  "planningObjectTypes": 2,
  "type": 18,
  "metadataFieldValues": [
    {
      "metadataFieldId": 33124,
      "stringValue": "NewValue_2_Modified",
      "description": "Description 2 Modified",
      "type": 18
    },
    {
      "metadataFieldId": 33124,
      "stringValue": "NewValue_1_Modified",
      "description": "Description 1 Modified",
      "type": 18
    }
  ]
}

Remove all field values from a Metadata Field

Send an empty metadataFieldValues[] list. This removes all field values for the Metadata Field.

{
  "name": "Example_Metadata_Field",
  "description": "",
  "ilapId": "R-4492d79c-5f1b-4008-9e69-b9213290a886",
  "iri": "",
  "isVisible": true,
  "planningObjectTypes": 2,
  "type": 18,
  "metadataFieldValues": []
}