Import Descriptions

Import a RSA G&L description file sent as the request body.

POST https://instance.securid.com/aveksa/command.submit?cmd=importDescriptions

note

The format parameter controls the input file format (xml or csv), not the response format. The response is always returned as key=value pairs regardless of the value passed.

The command does not accept format=json.

Request

Parameters

command	importDescriptions
format	xml - (Default) Input file is in XML format. csv - Input file is in comma-separated format. See Body for the required CSV column structure.
behavior	Determines what happens when the import file contains descriptions that already exist. skip - Leave existing descriptions unchanged and skip them. overwrite - Replace existing descriptions with the imported values. fail - (Default) Abort the import if any existing description is found.
filename	The filename in the import directory on the G&L server. The import directory is specified on the Web Services configuration page. Not recommended. Send the file as the request body instead.
appscope	true - The CSV file includes an application scope column. false - (Default) The CSV file does not include an application scope column.

Headers

Authorization	Bearer token
Accept	application/json
Content-Type	application/xml

Body

Send the descriptions file as the raw request body.

XML format (format=xml)

The root element is <BusinessDescriptions>. Each <BusinessDescription> element describes one description entry.

<BusinessDescriptions>
    <BusinessDescription type="Application" exactmatch="true" filter="AppName">
        <AltName>Application Display Name</AltName>
        <Tooltip/>
        <LongDesc/>
        <HelpURL/>
    </BusinessDescription>
    <BusinessDescription type="Entitlement" exactmatch="true" filter="Entitlement Name">
        <AltName>Entitlement Display Name</AltName>
        <Tooltip/>
        <LongDesc>Description text</LongDesc>
        <HelpURL/>
    </BusinessDescription>
    <BusinessDescription type="GlobalRole" exactmatch="true" application="RoleBS" filter="Role Name">
        <AltName>Role Display Name</AltName>
        <Tooltip/>
        <LongDesc/>
        <HelpURL/>
    </BusinessDescription>
</BusinessDescriptions>

Valid type attribute values: Application, ApplicationRole, Entitlement, GlobalRole, UserGroup

CSV format (format=csv)

The first row must be a header row with these columns (in any order):

TYPE,FILTER,EXACTMATCH,ALT_NAME,TOOLTIP,LONG_DESC,HELP_URL
Application/Directory,AppName,true,Application Display Name,,,
Entitlement,Entitlement Name,true,Entitlement Display Name,,Description text,

Valid TYPE column values: Application/Directory, ApplicationRole, Entitlement, GlobalRole, UserGroup

Response

Parameters

num-created	The number of descriptions created.
num-overwritten	The number of descriptions overwritten.
num-skipped	The number of descriptions skipped.

Examples

Request

Curl

curl -K -X POST \
"https://instance.securid.com/aveksa/command.submit?cmd=importDescriptions&format=xml&behavior=overwrite" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/xml" \
-d '<BusinessDescriptions>
    <BusinessDescription type="Application" exactmatch="true" filter="AppName">
        <AltName>Application Display Name</AltName>
        <Tooltip/>
        <LongDesc/>
        <HelpURL/>
    </BusinessDescription>
</BusinessDescriptions>'

Python

import requests

url = "https://instance.securid.com/aveksa/command.submit"

params = {
    "cmd": "importDescriptions",
    "format": "xml",
    "behavior": "overwrite"
}

headers = {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/xml'
}

body = """<BusinessDescriptions>
    <BusinessDescription type="Application" exactmatch="true" filter="AppName">
        <AltName>Application Display Name</AltName>
        <Tooltip/>
        <LongDesc/>
        <HelpURL/>
    </BusinessDescription>
</BusinessDescriptions>"""

response = requests.post(url, data=body, params=params, headers=headers)

if response.status_code == 200:
    print(response.text)
else:
    print(f"Request failed with status code {response.status_code}")

Node.js

const axios = require('axios');

const url = "https://instance.securid.com/aveksa/command.submit";

const params = {
    cmd: "importDescriptions",
    format: "xml",
    behavior: "overwrite"
};

const headers = {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/xml'
};

const body = `<BusinessDescriptions>
    <BusinessDescription type="Application" exactmatch="true" filter="AppName">
        <AltName>Application Display Name</AltName>
        <Tooltip/>
        <LongDesc/>
        <HelpURL/>
    </BusinessDescription>
</BusinessDescriptions>`;

axios.post(url, body, { params, headers })
    .then(response => {
        if (response.status === 200) {
            console.log(response.data);
        } else {
            console.log(`Request failed with status code ${response.status}`);
        }
    })
    .catch(error => {
        console.error('Error:', error);
    });

Response

200

The response is always returned as key=value pairs regardless of the format parameter.

num-created=1
num-skipped=0
num-overwritten=0

412 Invalid Format

Returned when format=json is passed. This command does not support JSON response format. The format parameter controls input file format only.

<html>
    <head>
        <title>Error</title>
    </head>
    <body>The format parameter must be a value of xml or csv
 Query String=cmd=importDescriptions&amp;format=json</body>
</html>

412 Filename Config

Returned when filename is used but no import directory is configured on the Web Services settings page.

<html>
    <head>
        <title>Error</title>
    </head>
    <body>The filename parameter cannot be used until the import directory is configured in the Web Services configuration screen.
 Query String=cmd=importDescriptions&amp;format=xml&amp;filename=test.xml</body>
</html>

500 No Body

Returned when the request body is missing.

<html>
    <head>
        <title>Error</title>
    </head>
    <body>java.lang.NullPointerException</body>
</html>

500 Format Mismatch

Returned when the body content does not match the specified format. For example, sending XML with format=csv.

<html>
    <head>
        <title>Error</title>
    </head>
    <body>com.aveksa.server.core.description.BusinessDescriptionException: Line 1: The "TYPE" column is an invalid value.
 TYPE can be one of the following values:
 Application/Directory, ApplicationRole, Entitlement, GlobalRole, UserGroup</body>
</html>

401 Invalid Token

<html>
    <head>
        <title>Error</title>
    </head>
    <body>The token is not valid for the command 'importDescriptions'. Token is invalid or expired</body>
</html>

401 No Token

<html>
    <head>
        <title>Error</title>
    </head>
    <body>The token is required for the command 'importDescriptions'</body>
</html>

Verified with RSA Governance & Lifecycle version 8.0.0.188886 P10_HF01.