Customer Integration Guide#

Customer service allows to manage customer entities. It is possible to create, disable, edit, fetch, list, search through customer entities. It is also possible to fetch some basic information like logo and user roles. In the future even more information will be available in the service.

Customer entities are grouped into customer groups, and each customer must belong to a parent and to a domain. Customer groups are used to facilitate permissions management.

It is important to be aware that several customer entities can belong to a single ‘real world’ client.

The service is used internally.

This documentation will focus on functionalities and structure of V2, which is currently in development. For detailed information about V1 please refer to the Swagger API documentation

Please read the General integration guide to learn the general concepts and common data structures used throughout the Argus API.

Tip

The Swagger API documentation is always up-to-date and lets you try out any query with your user session or an API-key.

In V2 the API has two parts: ‘basic’ for fetching information and ‘admin’ which provides access to CRUD operations.

Basic API: Fetching a customer#

Fetching a single customer is done using the customer id or shortname

curl -H "Argus-API-Key: my/api/key" -X GET https://api.mnemonic.no/customers/v2/customer/idOrShortname

If successful, the above invocation will return the customer basic model:

{
  "data": {
    "id": 0,
    "name": "string",
    "shortName": "string",
    "domain": {
      "id": 0,
      "name": "string"
    },
    "flags": [
      "disabled"
    ],
    "type": "GROUP"
  }
}

All endpoints for fetching, searching/listing, updating and disabling a customer return the same datamodel.

See the Swagger API documentation for details on the returned data model.

Basic API: Fetching customer user roles#

This endpoint returns a list of customer roles. This endpoint is not yet populated with data.

    curl -H "Argus-API-Key: my/api/key" -X GET "https://api.mnemonic.no/customers/v2/customer/idOrShortname/userroles"

Basic API: Fetching properties#

This endpoint returns a list of properties limited by limit and offset. The list can be filtered by property keys. The list includes default values from the descriptors.

curl -X 'GET' 
'https://api.mnemonic.no/customers/v2/customer/idOrShortName/properties?domain=domain%20&name=key1&name=key2&includeUnset=false&offset=0&limit=25' 
-H 'accept: application/json' 
-H 'Argus-API-Key: my/api/key'

Basic API: Searching for customers#

Searching for customers can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General integration guide to learn about general concepts for search endpoints.

Basic API: Listing domains#

This endpoint is located in a separate subsection of the API, called domain. It returns a list of domains limited by limit and offset:

curl -H "Argus-API-Key: my/api/key" -X GET "https://api.mnemonic.no/customers/v2/domain?offset=0&limit=25"

Admin API: Fetching a customer#

Fetching a single customer is done using the customer id or shortname, same as in the Basic endpoint.

curl -H "Argus-API-Key: my/api/key" -X GET https://api.mnemonic.no/customeradmin/v2/customer/idOrShortname

If successful, the above invocation will return the customer admin model:

{
  "data": [
    {
      "id": 0,
      "name": "string",
      "shortName": "string",
      "domain": {
        "id": 0,
        "name": "string"
      },
      "flags": [
        "disabled"
      ],
      "type": "group",
      "timeZone": {
        "description": "string"
      },
      "createdByUser": {
        "id": 0,
        "shortName": "string",
        "name": "string",
        "domain": {
          "id": 0,
          "name": "string"
        },
        "customer": {
          "id": 0,
          "name": "string",
          "shortName": "string",
          "domain": {
            "id": 0,
            "name": "string"
          }
        }
      },
      "createdTimestamp": 0,
      "lastUpdatedByUser": {
        "id": 0,
        "shortName": "string",
        "name": "string",
        "domain": {
          "id": 0,
          "name": "string"
        },
        "customer": {
          "id": 0,
          "name": "string",
          "shortName": "string",
          "domain": {
            "id": 0,
            "name": "string"
          }
        }
      },
      "lastUpdatedTimestamp": 0,
      "deletedTimestamp": 0,
      "deletedByUser": {
        "id": 0,
        "shortName": "string",
        "name": "string",
        "domain": {
          "id": 0,
          "name": "string"
        },
        "customer": {
          "id": 0,
          "name": "string",
          "shortName": "string",
          "domain": {
            "id": 0,
            "name": "string"
          }
        }
      },
      "language": "norwegian",
      "parent": {
        "id": 0,
        "name": "string",
        "shortName": "string",
        "domain": {
          "id": 0,
          "name": "string"
        }
      }
    }
  ]
}

All endpoints in the Admin API for fetching, searching/listing, updating and disabling a customer return the same Admin Customer datamodel.

See the Swagger API documentation for details on the returned data model.

Admin API: Fetching customer user roles#

This endpoint returns a list of customer roles. This endpoint is not yet populated with data.

    curl -H "Argus-API-Key: my/api/key" -X GET "https://api.mnemonic.no/customeradmin/v2/customer/idOrShortname/userroles"

Admin API: Searching for customers#

Searching for customers can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General integration guide to learn about general concepts for search endpoints.

Simple search#

For simple search it is possible to search for customers by keywords and filter out the results by parent id or shortname

curl -H "Argus-API-Key: my/api/key"  -X GET "https://api.mnemonic.no/customeradmin/v2/customer?keywords=&parent="

Other parameters include limit, offset and sort.

Advanced search#

Advanced search has access to all possible filtering parameters for customer, and follows the general advanced search structure as described in the General integration guide.

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json" https://api.mnemonic.no/customeradmin/v2/customer/search -d '{
  "customer":["shortname1", "2"],
  "parent":["1","shortname2"],
  "domain":["1", "otherDomain"],
  "includeDeleted":false,
  "includeFlags":[FlagEnumValue1, FlagEnumValue2],
  "excludeFlags":[FlagEnumValue3, FlagEnumValue4],
  "keywords":["keyword1","keyword2"],
  "keywordMatchStrategy":KeywordMatchStrategyEnumValue,
  "keywordFieldStrategy":[KeywordFieldStraregyEnumValue1, KeywordFieldStraregyEnumValue2],
  "subCriteria":[SearchBasicCustomerRequestSubCriteria1, SearchBasicCustomerRequestSubCriteria2],
  "limit":25,
  "offset":0,
  "sortBy":[SortBy1, SortBy2]
}'

See the Swagger API documentation for more details on valid request parameters.

Subcriteria#

Subcriteria are discussed in detail in the General integration guide. We provide some examples related to the Customer API here, but the concepts for subcriteria are described more in detail there.

Using subcriteria allows you to fetch several different dimensions of data in one query, or express which data to exclude. By default, subqueries will be combined with an “OR” logic.

Subqueries with *exclude=true* define a set of criteria for cases to exclude:

curl -X POST -H "Argus-API-Key: my/api/key" -H "Content-Type: application/json"  https://api.mnemonic.no/customeradmin/v2/customer/search -d  '{
  "parent":["mycustomerGroup1"],
  "includeFlags":["excludeFromProduction"],   
  "subCriteria": [
     {"includeFlags":["disabled","customerDataDeleted"],
      "exclude":false}
   ]
}'

Admin API: Listing domains#

This endpoint is located in a separate subsection of the API, called domain. It returns a list of domains limited by limit and offset:

curl -H "Argus-API-Key: my/api/key" -X GET "https://api.mnemonic.no/customeradmin/v2/domain?offset=0&limit=25"

Admin API: Creating new customer#

This endpoint creates new customer in the system, based on a set of parameters. It returns the newly created customer. To create a customer group, please specify type ‘group’ in the request. To create a non-group customer the type should be ‘leaf’.

curl -X 'POST' 
  'https://api.mnemonic.no/customeradmin/v2/customer' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key' 
  -d '{
  "name": "string",
  "shortName": "string",
  "domain": "string",
  "parent": "string",
  "language": "norwegian",
  "timeZone": "string",
  "type": "group",
  "excludeFromProduction": true,
  "networkBaseCustomer": true,
  "singleNetworkDomain": true
}'

Admin API: Updating customer#

This endpoint allows to modify existing customer. It returns the updated customer. It’s possible to change the following:

  • name

  • short name

  • language

  • timezone

  • setting for the following flags:

    • denySubmitForAnonymousUser

    • allowGlobalData

    • excludeFromProduction

    • networkBaseCustomer

    • singleNetworkDomain

    • dataDeleted

curl -X 'PUT' 
  'https://api.mnemonic.no/customeradmin/v2/customer/idOrShortName?domain=domain' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "name": "string",
  "shortName": "string",
  "language": "norwegian",
  "timeZone": "string",
  "denySubmitForAnonymousUser": true,
  "allowGlobalData": true,
  "excludeFromProduction": true,
  "networkBaseCustomer": true,
  "singleNetworkDomain": true,
  "dataDeleted": true
}'

Admin API: Disabling customer#

This endpoint allows to disable customer, it should be used after customer data is deleted. The flag ‘Disabled’ is set on the customer object, but it remains in our db for reference purposes. The disabled customer will no longer show up in searches, unless specifically requested. Only admins that have access privileges for the customer’s parent will be able to view it.

curl -X 'PUT' 
  'https://api.mnemonic.no/customeradmin/v2/customer/idOrShortName?domain=domain' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Admin API: Re-enabling customer#

This endpoint allows reenabling a disabled customer.

curl -X 'PUT' 
'https://api.mnemonic.no/customeradmin/v2/customer/idOrShortName/reenable?domain=domain' 
-H 'accept: application/json' 
-H 'Argus-API-Key: my/api/key'

Admin API: Moving customer#

This endpoint allows the admins to change the parent of the customer. The new parent has to be of group type, and the move should not grant any additional privileges to new users.

curl -X 'PUT' 
'https://api.mnemonic.no/customeradmin/v2/customer/idOrShortName/move?domain=domain' 
-H 'accept: application/json' 
-H 'Content-Type: application/json' 
-H 'Argus-API-Key: my/api/key'
-d '{
"parent": "string"
}'

Admin API: Fetching properties#

This endpoint returns a list of properties limited by limit and offset. The list can be filtered by property keys. The list includes default values from the descriptor.

curl -X 'GET' 
'https://api.mnemonic.no/customeradmin/v2/customer/idOrShortName/properties?domain=domain%20&name=key1&name=key2&includeUnset=false&offset=0&limit=25' 
-H 'accept: application/json' 
-H 'Argus-API-Key: my/api/key'

Admin API: Updating properties#

This endpoint allows updating existing customer properties or adding new ones. Inserted values are validated against the descriptor and accepted only if they are of correct type and have the proper format. It is not possible to update a property that has no descriptor set up.

curl -X 'PUT' 
'https://api.mnemonic.no/customeradmin/v2/customer/idOrShortName/properties?domain=domain' 
-H 'accept: application/json' 
-H 'Content-Type: application/json' 
-H 'Argus-API-Key: my/api/key'
-d '{
"properties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}'

Admin API: Deleting properties#

This endpoint allows the user to reset properties to property descriptor’s default.

curl -X 'DELETE' 
'https://api.mnemonic.no/customeradmin/v2/customer/idOrShortName/properties?domain=domain&key=key1&key=key2' 
-H 'accept: application/json' 
-H 'Argus-API-Key: my/api/key'

Admin API: Updating user roles#

To update customer user roles you need to provide which role to update and which user (id or shortname) should be responsible.

curl -X 'PUT' 
'https://api.mnemonic.no/customeradmin/v2/customer/idOrShortName/userroles?domain=domain' 
-H 'accept: application/json' 
-H 'Content-Type: application/json' 
-H 'Argus-API-Key: my/api/key'
-d '{
"userRoles": [
{
"role": "technicalAccountManager",
"user": "idOrShortName"
}
]
}'

Admin API - Property Descriptor Management: fetch property descriptor by id or key#

Needed permissions: viewCustomerPropertyDescriptors

This endpoint returns a property descriptor identified by UUID or key. The response can optionally include Json Schema, (settable via query parameter). If include Json Schema query parameter is set to false, JSON Schema field in the response will be null. For basic types JSON Schema is generated and for type jsonType JSON Schema is returned as saved in the db.

curl -X 'GET' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/uuidOrKey?includeSchema=false' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

PropertyDescriptorResponse model will be returned. Note:All endpoints for fetching, searching/listing, creating and updating and disabling a property descriptor return the same data model.

{"id": "c4c32359-2aa0-4448-834d-aa54afa1153b",
    "key": "test2",
    "description": "very good",
    "localizedDescription": "very good",
    "localizedDescriptions": {
      "norwegian": "veldig bra",
      "english": "very good"
    },
    "createdByUser": {
      "type": "user",
      "id": 23,
      "shortName": "someUser",
      "name": "Some User",
      "domain": {
        "id": 1,
        "name": "MNEMONIC"
      },
      "customer": {
        "id": 1,
        "name": "mnemonic",
        "shortName": "mnemonic",
        "domain": {
          "id": 1,
          "name": "MNEMONIC"
        }
      }
    },
    "lastUpdatedByUser": {
      "type": "user",
      "id": 23,
      "shortName": "someUser",
      "name": "Some User",
      "domain": {
        "id": 1,
        "name": "MNEMONIC"
      },
      "customer": {
        "id": 1,
        "name": "mnemonic",
        "shortName": "mnemonic",
        "domain": {
          "id": 1,
          "name": "MNEMONIC"
        }
      }
    },
    "deletedByUser": null,
    "createdTimestamp": 1678206365456,
    "lastUpdatedTimestamp": 1678206365456,
    "deletedTimestamp": 0,
    "flags": [],
    "defaultValue": "string",
    "section": "notification",
    "type": "string",
    "jsonSchema": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "string"
    }
  }

Admin API - Property Descriptor Management: update property descriptor#

Needed permissions: updateCustomerPropertyDescriptor

This endpoint allows the user to update a property descriptor identified by UUID or key by using data from the request. It is possible to update:

  • localizedDescriptions - english description is required and can not be deleted or updated to “”

  • section

  • defaultValue - has to be valid according to type (for the validation rules for jsonType read on JSON Schema validation)

  • type - if update to jsonType JSON Schema must be provided in addition

  • schema - possible to update only for type jsonType, Note: it is not possible to update both default value and JSON Schema at the same time, when updating the schema it is verified if the default value is still valid according to the schema and when the default value is updated it is always validated against the schema for the jsonType

  • deprecated - flag the descriptor as deprecated (has to be done before the descriptor is deleted)

curl -X 'PUT' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/uuidOrKey' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "localizedDescriptions": {
    "english": "string",
    "norwegian": "string"
  },
  "section": "notification",
  "defaultValue": "string",
  "type": "string",
  "schema": "JsonNode",
  "deprecated": false
}'

Admin API - Property Descriptor Management: delete property descriptor#

Needed permissions: deleteCustomerPropertyDescriptor

This endpoint allows the user to delete a previously deprecated property descriptor identified by UUID or key. Please note that some customers may still have values for the descriptor, check the log message for information.

curl -X 'DELETE' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/uuidOrKey' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Admin API - Property Descriptor Management: fetch JSON Schema for a property descriptor by id or key#

Needed permissions: viewCustomerPropertyDescriptors

This endpoint returns a JsonNode with JSON Schema for a property descriptor identified by UUID or key. For basic types schema is generated and for jsonType the schema saved in db is returned.

curl -X 'GET' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/uuidOrKey/jsonschema' 
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Admin API - Property Descriptor Management: Searching for descriptors#

Needed permissions: viewCustomerPropertyDescriptors

Searching for descriptors can be done using the simple search GET endpoint or the advanced search POST endpoint.

Please read the General integration guide to learn about general concepts for search endpoints.

Simple search#

For simple search it is possible to search for descriptors by keywords and sort the results

curl -X 'GET'  
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor?offset=0&limit=25'
  -H 'accept: application/json' 
  -H 'Argus-API-Key: my/api/key'

Other parameters include limit and offset.

Advanced search#

Advanced search has access to all possible filtering parameters for property descriptors, and follows the general advanced search structure as described in the General integration guide.

curl -X 'POST'   
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor/search' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "section": [
    "notification"
  ],
  "type": [
    "string"
  ],
  "includeFlags": [
    "deleted"
  ],
  "excludeFlags": [
    "deprecated"
  ],
  "keywords": [
    "string"
  ],
  "subCriteria": [
    {
      "section": [
        "notification"
      ],
      "type": [
        "string"
      ],
      "includeFlags": [
        "deprecated"
      ],
      "excludeFlags": [
        "deprecated"
      ],
      "keywords": [
        "string"
      ],
      "subCriteria": [
        "string"
      ],
      "required": false,
      "exclude": false
    }
  ],
  "includeDeleted": false,
  "limit": 0,
  "offset": 0,
  "sortBy": [
    "key"
  ]
}'

Note: “keywordMatchStrategy” and “keywordFieldStrategy” search options are not supported. See the Swagger API documentation for more details on valid request parameters.

Admin API - Property Descriptor Management: add a new property descriptor#

Needed permissions: createCustomerPropertyDescriptors

This endpoint creates a descriptor based on parameters provided

  curl -X 'POST' 
  'https://api.mnemonic.no/customeradmin/v2/propertydescriptor' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/json' 
  -H 'Argus-API-Key: my/api/key'
  -d '{
  "key": "test2",
  "localizedDescriptions": {
    "norwegian": "veldig bra",
    "english": "very good"
  },
  "section": "notification",
  "defaultValue": "string",
  "type": "string",
  "schema": ""
}'

Note: the default value will be validated against the type provided and for jsonType it will be validated against JSON Schema. Note 2: description in english is required.