13.4 Reporting REST API

The Reporting REST API provides the ability to write custom reporting applications, as well to create a custom command-line client for automation.

To use the Reporting REST API, you need to follow these steps:

  1. Use the Authentication REST API to get an authentication token. For details, see Section 13.3, Authentication REST API.

  2. Carry the token with the Reporting REST API you want to use in the HTTP header. For details, see the appropriate REST API below.

  3. Detect token expiration. When the Reporting REST API returns a 401 (even if you carry the token in the request), this means the token has expired. In this case, repeat Step 1.

  4. When you are done using the Reporting REST APIs, invalidate the token by performing a Logout operation. To do this, issue a DELETE request for the token. For details, see Section 13.3.2, DELETE auth/tokens{token}.

The remainder of this section describes the REST endpoints available for reporting:

13.4.1 GET /rpt/definitions

Gets report definitions.

This operation returns summary information about report definitions. The server sorts the data. The DisplayName and Description are localized based on the Accept-Language HTTP header.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

These URL parameters are required:

  • sortBy: The column to sort by. Valid values: DisplayName, Description, Tags. The server validates the value.

  • sortOrder: The sort order. Valid values: ASC or DESC. The server validates the value.

  • idxFrom: The starting row index. 0 is the first.

  • idxTo: The ending row index, inclusive. The server validates that the idxTo value is greater than the idxFrom value.

These URL parameters are optional:

  • DisplayName: Specifies a “contains ignore case” filter on DisplayName. When occurring in the URL multiple times, the filter strings are ANDed together.

  • Description: Specifies a “contains ignore case” filter on Description. When occurring in the URL multiple times, the filter strings are ANDed together.

  • Category: Specifies a “string match ignore case” filter on Category. When occurring in the URL multiple times, the filter strings are ANDed together.

  • Tags: Specifies a “string match ignore case” filter on a Tag. When occurring in the URL multiple times, the filter strings are ANDed together.

  • LOP: Indicates whether to OR/AND the conditions together. The default is AND if not present.

Data to Send

None.

Response

None.

Status Code: 200 OK

Here is the payload:

{
  "TotalSize":10,
  "Definitions":[
    {"GUID":"myResource0",
    "DisplayName":"My Resource0",
    "Description":"My Resource Description99",
    "Categories":["resource"],
    "Link":"definitions/myResource0"},
more...
  ]
}

Status Code: 400 Parameter Error

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"InvalidOrderBy"}
    },
   "Reason":{"Text":"Invalid sortOrder url parameter specified: ASCENDING.  Valid values are ASC, DESC"}
  }
}

Here are the fault subcodes:

  • InvalidOrderBy: if the order by was not a valid value

  • InvalidTemplateRange

  • InvalidSortBy

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.2 POST /rpt/definitions

Copies a report definition.

This operation copies a definition and returns the generated GUID.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

This URL parameter is required:

  • copy=<GUID>: Copies an existing defintion, but does not include any Data to Send. The server copies an existing definition and appends localized “_copy[n]” to DisplayName in every locale bundle where n is a number starting with 1.

Data to Send

None.

Response

None.

Status Code: 200 OK

Here is the payload:

{"GUID":"f3aed01ef7ed4783b636ef3dfecf6321","Status":"OK"}

Status Code: 404 Not Found

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"ReportTemplateCreateCopyNotExist"}
     },
   "Reason":
     {"Text":"Report template creation failed.  The report template created failed because report template to copy 'f3aed01ef7ed4783b636ef3dfecf6321' does not exist."}
   }
}

Here are the fault subcodes:

  • ReportTemplateCreateCopyNotExist: If the template to copy was not found.

  • ReportTemplateCreateNoContent: Not a copy and no content.

  • ReportTemplateCreateFailedBadMediaType: If report format is not PDF or CSV.

  • ReportTemplateCreateFailedNeedDisplayName: If display name is not supplied.

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.3 GET /rpt/defintions/<GUID>

Gets a definition.

Gets the detailed info on the definition specified. Display name, description of the report as well as display name and description of the report parameters will be sent in the language based upon the Accept-Language http header.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None.

Data to Send

None.

Response

None.

Status Code: 200 OK

Here is the payload:

{
  "DisplayName":"My Resource0_copy1",
  "Description":"My Resource Description99",
  "Categories":["resource"],
  "Tags":["resources","mary"],
  "PluginParameterDefinitions":
      [{"Type":"String",
        "DisplayName":"PLUGIN_DIRECTORY",
        "InternalName":"PLUGIN_DIRECTORY",
        "Description":"Location of plugin files",
        "DefaultValue":"",
        "IsForPrompting":"0"},  
       {"Type":"String",
        "DisplayName":"Language",
        "InternalName":"REPORT_LOCALE",
        "Description":"Select the language in which the report will be generated.",
        "DefaultValue":"en",
        "IsForPrompting":"1",
        "Options":
          {"Property":
              [{"Value":"en","DisplayName":"English","Name":"%English"},
               {"Value":"fr","DisplayName":"French","Name":"%French"},
               {"Value":"de","DisplayName":"German","Name":"%German"},
               {"Value":"it","DisplayName":"Italian","Name":"%Italian"},
               {"Value":"ja","DisplayName":"Japanese","Name":"%Japanese"},
               {"Value":"zh_TW","DisplayName":"Traditional Chinese","Name":"%Traditional Chinese"},
               {"Value":"zh","DisplayName":"Simplified Chinese","Name":"%Simplified Chinese"},
               {"Value":"es","DisplayName":"Spanish","Name":"%Spanish"},
               {"Value":"pt","DisplayName":"Portuguese","Name":"%Portuguese"}]
          }
      ]
    },
  "Comments":"This is my comment",
  "Email":
    {"To":
      ["allison blake <ablake@novell.com>",
       "chip nano <cnano@novell.com>"],
     "Cc":
       ["fred stats <fstats@novell.com>",
       "bob bender <bbender@novell.com>"],
     "Subject":"Please verify",
     "Message":"See attached report."},
  "Format":"PDF",
  "Links": 
    {"Export":"templates/b7785943f5ea48329d0c5b1c4af1a1cc/rpz",
     "Scheduling":"templates/b7785943f5ea48329d0c5b1c4af1a1cc/sched"}
}

Response header: Etag: {hex string}

Status Code: 404 Not Found

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"ReportTemplateDoesNotExist"}
     },
   "Reason":
     {"Text":"The report template 'b7785943f5ea48329d0c5b1c4af1a1cc11' does not exist."}
   }
}

Here is the fault subcode:

  • ReportTemplateDoesNotExist: If the template was not found.

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.4 PUT /rpt/definitions/<GUID>

Updates a definition.

Update an existing definition. Display name, description of the report as well as display name and description of the report parameters will be interpreted to be in the language based on the Accept-Language HTTP header.

RepeatUnit: Valid values are NONE, DAY, WEEK, MONTH (12 MONTH = 1 year, 3 MONTH = 1 quarter). NONE is used only in REST API (not to the end user) to represent non-repeating (one time) schedule. When repeat unit is set to NONE, only start date is meaningful.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

Here is the payload:

{
  "DisplayName":"My Resource0_copy1",
  "Description":"My Resource Description99",
  "Categories":["resource"],
  "Tags":["resources","mary"],
  "PluginParameterDefinitions":
      [{"Type":"String",
      "DisplayName":"PLUGIN_DIRECTORY",
      "InternalName":"PLUGIN_DIRECTORY",
      "Description":"Location of plugin files",
      "IsForPrompting":"0"}
     ],
  "Comments":"This is my comment",
  "Email":
    {"To":
      ["allison blake <ablake@novell.com>",
       "chip nano <cnano@novell.com>"],
     "Cc":
       ["fred stats <fstats@novell.com>",
       "bob bender <bbender@novell.com>"],
     "Subject":"Please verify",
     "Message":"See attached report."},
  "Format":"PDF",
}

Request Header (optional) If-Match: {hex string}

If this string is sent, it is is compared to the current etag for the report. If it does not match, an ncac “ReportChangedSinceRetrieve” is thrown.

Response

None.

Status Code: 200 OK

Here is the payload:

{"GUID":"f3aed01ef7ed4783b636ef3dfecf6321","Status":"OK"}

Response Header Etag: {hex string}

Status Code: 404 Not Found, 409 Conflict

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"ReportTemplateDoesNotExist"}
    },
   "Reason":
     {"Text":"Report template 'f3aed01ef7ed4783b636ef3dfecf6321' does not exist."}
   }
}

Here are the fault subcodes:

  • ReportTemplateDoesNotExist: If the template was not found.

  • ReportTemplateUpdateDuplicateDisplayName: For duplicate display name

  • ReportTemplateCreateFailedBadMediaType: If report format is not PDF or CSV

  • ReportTemplateCreateFailedNeedDisplayName: If display name is not supplied

  • ReportChangedSinceRetrieve: If contents have changed since the retrieval

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.5 DELETE /rpt/definitions/<GUID>

Deletes an existing definition. Any scheduled runs are also deleted.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None.

Response

None.

Status Code: 200 OK

Here is the payload:

{"GUID":"f3aed01ef7ed4783b636ef3dfecf6321","Status":"OK"}

Status Code 404: Not Found

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"ReportTemplateDoesNotExist"}
    },
   "Reason":
     {"Text":"Report template 'f3aed01ef7ed4783b636ef3dfecf6321' does not exist."}
   }
}

Here are the fault subcodes:

  • ReportTemplateDoesNotExist: If the template was not found.

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.6 GET /rpt/definitions/<GUID>/rpz

Gets a definition RPZ.

Gets the JAR of the definition for export. The JAR includes the jrxml, localization bundle, and tempate meta-data.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None.

Data to Send

None.

Response

None.

Status Code: 200 OK

Here is the payload:

application/zip

Status Code: 404 Not Found

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"ReportTemplateDoesNotExist"}
    },
   "Reason":
     {"Text":"Report template 'f3aed01ef7ed4783b636ef3dfecf6321' does not exist."}
   }
}

Here are the fault subcodes:

  • ReportTemplateDoesNotExist: If the template was not found.

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.7 GET /rpt/definitions/<guid>/paramdefs/<paramName>

Gets parameter name/value pairs.

This operation will return a list of allowable values for a given parameter. These values may come from the database, or they may be part of hardcoded options.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

The following URL parameters are required:

  • casading parameter value if cascading parameters are used for the paramName. This is illustrated in the following example:

    <PluginParameterDefinition> 
   <Type>String</Type> 
   <DisplayName>Search User(s)</DisplayName> 
   <Description>Specifies the search criteria to choose user(s) to be reported.</Description> 
   <InternalName>search_name</InternalName> 
   <DefaultValue></DefaultValue> 
   <IsForPrompting>0</IsForPrompting> 
  </PluginParameterDefinition> 
  <PluginParameterDefinition> 
   <Type>String</Type> 
   <DisplayName>User(s)</DisplayName> 
   <Description>Specifies the user(s) from which data will be reported.</Description> 
   <InternalName>sample</InternalName> 
   <DefaultValue></DefaultValue> 
   <IsForPrompting>1</IsForPrompting> 
   <OptionQuery>SELECT first_name || ' ' || last_name as name, '\'' || identity_id || '\'' as value FROM idm_rpt_data.idmrpt_identity where lower(first_name || ' ' || last_name) like lower('##search_name##') order by name</OptionQuery> 
  </PluginParameterDefinition>

The following URL parameters are optional:

  • idxFrom: The starting row index. 0 is the first.

  • idxTo: The ending row index, inclusive. Server will validate that idxTo >= idxFrom

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{"TotalSize":19,"ParameterValues":[
{"DisplayName":"Abby Spencer","Value":"'cee9e6b0fb654adfb5ec22eb62c39557'"},
{"DisplayName":"Adam Marsden","Value":"'cee9e6b0fb654adfb5ec22eb62c393f8'"},
{"DisplayName":"Allison Blake","Value":"'cee9e6b0fb654adfb5ec22eb62c39556'"},
{"DisplayName":"Angie Chung","Value":"'cee9e6b0fb654adfb5ec22eb62c39558'"},
{"DisplayName":"Anthony Palani","Value":"'cee9e6b0fb654adfb5ec22eb62c39559'"},
{"DisplayName":"April Smith","Value":"'cee9e6b0fb654adfb5ec22eb62c39560'"},
{"DisplayName":"Bill Bender","Value":"'cee9e6b0fb654adfb5ec22eb62c39561'"},
{"DisplayName":"Bill Brown","Value":"'cee9e6b0fb654adfb5ec22eb62c39563'"},
{"DisplayName":"Bill Burke","Value":"'cee9e6b0fb654adfb5ec22eb62c39562'"},
{"DisplayName":"Bob Jenner","Value":"'cee9e6b0fb654adfb5ec22eb62c39564'"},
{"DisplayName":"Brad Jones","Value":"'cee9e6b0fb654adfb5ec22eb62c39565'"},
{"DisplayName":"Cal Central","Value":"'cee9e6b0fb654adfb5ec22eb62c39566'"},
{"DisplayName":"Chip Nano","Value":"'cee9e6b0fb654adfb5ec22eb62c39567'"},
{"DisplayName":"Chris Black","Value":"'cee9e6b0fb654adfb5ec22eb62c39568'"},
{"DisplayName":"David Decker","Value":"'cee9e6b0fb654adfb5ec22eb62c39555'"},
{"DisplayName":"Josh Kelley","Value":"'cee9e6b0fb654adfb5ec22eb62c39570'"},
{"DisplayName":"Kelly Kilpatrick","Value":"'cee9e6b0fb654adfb5ec22eb62c39569'"},
{"DisplayName":"Kip Keller","Value":"'cee9e6b0fb654adfb5ec22eb62c39571'"},
{"DisplayName":"Rashelle Bradley","Value":"'cee9e6b0fb654adfb5ec22eb62c393f6'"}]}

Status Code: 400 parameter error

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"ReportParamNotFound"}
    },
   "Reason":{"Text":"Unable to return parameter values because supplied parameter 'abc' not found in report."}
  }
}

Here are the fault subcodes:

  • ReportParamNotFound

  • InvalidReportDefinitionRange

  • RequiredCascadingParamMissing

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.8 POST /rpt/definitions/import

Imports .spz or .rpz report(s).

Imports a zip file for a single definition or a zip of a zip for multiple definitions. The following rules apply:

  • The format of each zip must follow the Sentinel plugin standard, with data from the package.xml containing the definition metadata. The file must have the extension .rpz for a single report, or use the extension .spz for the case of multiple reports.

  • Each zip within the spz will be processed as if uploaded separately.

  • If overwrite parameter is true, then if a name already exists, it will be overwritten and have an individual status of OK.

  • If overwrite parameter is false or not present, anything that already exists will have individual status of FAILED, but overall status is still OK.

  • PlatformName must be included in the package.xml of the .rpz and that must be IDM, else error.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

There are no required URL parameters.

The following URL parameters are optional:

  • overwrite: true or false

  • token: the user authentication token

  • ts_url: the token server URL

  • format: the format of the content to return

  • content: the content type of the return value separate from the format

  • uploadid: the temporary id to use for this current upload

Data to Send

Multipart application/octet-stream.

Response

None

Status Code: 200 OK

Here is the payload:

{    
  “Status”: “OK”,
  “Imports”: [
     {“Filename” : “mary.rpz”, “GUID”: “24352345”, “Status”, “OK”},
     {“Filename” : “frank.rpz”, “Status”: “FAILED”, 
         "Fault":
           {"Code":
             {"Value":"Sender",
              "Subcode": {"Value":"ReportTemplateUpdateDuplicateDisplayName"}
             },
            "Reason": {"Text":"Report template update failed.  The report template update with GUID 'roleReport' failed because display name 'Role Report' is used in another report template."}
           }
      },
      more jars...
   ]
}

Possible Errors

These are the possible errors:

  • ReportDefinitionCreateDuplicateDisplayName

  • ReportTemplateCreateFailedBadMediaType

  • ReportTemplateCreateFailedNeedDisplayName

  • ReportUploadFailed

  • RpzFileUploadFailedZipException

  • RpzFileUploadFailedZipExceptionBadPackageXml

  • RpzFileUploadFailedZipExceptionBadPackageXmlNameTooLong

  • RpzFileUploadFailedReportContentNotIdm

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.9 GET /rpt/definitions/import/<upload id>

Gets the status of the JAR upload in progress.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{    
  “CompletedPercent”: 50,
  “Completed”: “10Mb”,
  “Total”: “20Mb”
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.10 DELETE /rpt/definitions/import/<upload id>

Cancels an upload.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{    
  “Cancelled”: “true”
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.11 GET /rpt/definition/<GUID> /sched

Gets schedules.

Get an array of schedules belonging to a specific definition.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
"TotalSize":1,
"Schedules":[
  {
  "ScheduleID":"e20cc23f-4de1-4002-8d5a-fecb8ccfceda",
  "DisplayName":"Identity Report – kkk","Schedule":{
    "StartDate":1275053400000,
    "EndDate":1275139800000,
    "RepeatNumber":1,
    "RepeatUnit":"MONTH"
  },
  "CollectOnRun":false
  }]
}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"ReportdefinitionDoesNotExist"}
     },
   "Reason":
     {"Text":"The report definition 'b7785943f5ea48329d0c5b1c4af1a1cc11' does not exist."}
   }
}

Here are the fault codes:

  • 404 InvalidURI: URI not found (Sender)

  • 500 InternalError: Server problem (Receiver)

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.12 POST /rpt/definition/<GUID>/sched

Creates a schedule.

Creates a new schedule for a specific definition. Here is the logic used for inheriting and overwriting attributes during schedule creation:

  • If an attribute is missing in the payload, its value is inherited from the definition; Otherwise, the value in payload will be taken.

  • For a mandatory attribute, there is no problem of doing so. However for an optional attribute, the ability of overwriting is limited. Here is an example:

    • Suppose definition A has an attribute called "attr1", which is *optional*. The default value of attr1 defined in definition A is "value1".

    • Now, suppose we create a schedule from definition A, and we do NOT want the optional attr1. How can we do it? If we don't put attr1 in the payload, the schedule will inherit "value1" from definition; If we put attr1 in the payload, then we have to specify its value.

    • The solution is that for optional attribute, we have to use composite value such as JSONObject or JSONArray. This way if we want to get rid of attr1, we put "attr1" : "{}" in the payload.

    • Fortunately we only have one optional attribute in our design, which is "Email". The rule is simple:

  • If there is no "Email" in payload, inherits definition's.

  • If there is "Email" in payload, but it has no "To" list or has empty "To" list, the schedule will not have email delivery.

  • If there is "Email" in payload, and it's "To" list contains at least one recipient, it overwrites definition's.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

{
"DisplayName":"Identity Report", 
"Description":"This report shows first name, last name, and job title for a given Identity used by the User Application", 
"Comments":"", 
"Format":"PDF", 
"CollectOnRun":false, 
"Email":{"To":[], "Cc":[], "Subject":"", "Message":""}, 
"Parameters":[
  {
  "Value":"", 
  "Description":"Location of plugin files", 
  "DisplayName":"PLUGIN_DIRECTORY", 
  "InternalName":"PLUGIN_DIRECTORY", 
  "IsForPrompting":"0", 
  "Type":"String", 
  "Required":"0"
  },
  {
  "Value":"D", 
  "Description":"Specifies the time period over which this report is run.", 
  "DisplayName":"Date Range", 
  "InternalName":"ReportType", 
  "IsForPrompting":"1", 
  "Type":"String", 
  "DisplayValue":"Current Day", 
  "OptionMultivalue":"0", 
  "Required":"0"
  },
  {
  "Value":"en", 
  "Description":"Select the language in which the report will be generated.", 
  "DisplayName":"Language", 
  "InternalName":"REPORT_LOCALE", 
  "IsForPrompting":"1", 
  "Type":"String", 
  "DisplayValue":"English", 
  "OptionMultivalue":"0", 
  "Required":"0"
  }
], 
"Schedule":{"StartDate":1275053400000, "RepeatNumber":1, "RepeatUnit":"MONTH", "EndDate":1275139800000}}

Response

None

Status Code: 201 OK

Here is the payload:

{"GUID":"e3dd599e-0476-4b76-b140-625d51372e79","Status":"OK"}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"ReportdefinitionDoesNotExist"}
     },
   "Reason":
     {"Text":"The report definition 'b7785943f5ea48329d0c5b1c4af1a1cc11' does not exist."}
   }
}

Here are the fault codes:

  • Sender

    • 404 InvalidURI: URI not found

    • 400 InvalidInput: Various input problems

  • Receiver

    • 500 InternalError: Server problem

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.13 GET /rpt/definition/<GUID>/sched/<sched GUID>

Gets a schedule.

Retrieves detailed information about the scheduled report.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
  "DisplayName":"My Resource0_copy1",
  "Description":"My Resource Description99",
  “CollectOnRun”:false,
  "Tags":["resources","mary"],
  "Parameters":
      [{"Type":"String",
      "DisplayName":"PLUGIN_DIRECTORY",
      "InternalName":"PLUGIN_DIRECTORY",
      "Description":"Location of plugin files",
      "IsForPrompting":"0",
      “Value”:”value”,
      “DisplayValue”:”value's display name”}
     ],
  "Comments":"This is my comment",
  "Email":
    {"To":
      ["allison blake <ablake@novell.com>",
       "chip nano <cnano@novell.com>"],
     "Cc":
       ["fred stats <fstats@novell.com>",
       "bob bender <bbender@novell.com>"],
     "Subject":"Please verify",
     "Message":"See attached report."},
  "Format":"PDF",},
  "Schedule":
    {"StartDate":1264873989592, 
     "RepeatNumber":1, 
     "RepeatUnit":"NONE", 
     "EndDate":1264874049592}
}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"?"}
     },
   "Reason":
     {"Text":"?"}
   }
}

Here are the fault codes:

  • 404 InvalidURI: URI not found (Sender)

  • 500 InternalError: Server problem (Sender)

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.14 DELETE /rpt/definition/<GUID>/sched/<sched GUID>

Deletes a schedule, and also removes all planned runs belonging to the schedule.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{"GUID":"e3dd599e-0476-4b76-b140-625d51372e79","Status":"OK"}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"?"}
     },
   "Reason":
     {"Text":"?"}
   }
}

Here are the fault codes:

  • 404 InvalidURI: URI not found (Sender)

  • 500 InternalError: Server problem (Receiver)

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.15 POST /rpt/definition/<GUID>/sched/<sched GUID>

Updates a schedule.

This operation modifies planned runs based on the parameter's value. There are two exclusive parameter sets. One and only one of them has to be present.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

This operation must have one and only one of the following parameter sets:

  • runToDel: the planned run to be deleted from this schedule.

  • shift: a delta that all planned runs will be shifted by. runToShift: which run the shift is based on. Both shift and runToShift have to be present.

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{"GUID":"e3dd599e-0476-4b76-b140-625d51372e79","Status":"OK"}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"?"}
     },
   "Reason":
     {"Text":"?"}
   }
}

Here are the fault codes:

  • Sender

    • 404 InvalidURI: URI not found

    • 400 InvalidInput: Various input problems

  • Receiver

    • 500 InternalError: Server problem

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.16 PUT /rpt/definition/<GUID>/sched/<sched GUID>

Updates a schedule.

Modifies an existing schedule.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

Same as POST /rpt/definition/<GUID>/sched

Response

None

Status Code: 200 OK

Here is the payload:

{"GUID":"e3dd599e-0476-4b76-b140-625d51372e79","Status":"OK"}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"?"}
     },
   "Reason":
     {"Text":"?"}
   }
}

Here are the fault codes:

  • Sender

    • 404 InvalidURI: URI not found

    • 400 InvalidInput: Various input problems

  • Receiver

    • 500 InternalError: Server problem

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.17 GET /rpt/reports

Gets completed reports.

Returns a list of minimal information on reports. The server performs the sorting.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

There are no required parameters.

The following URL parameters are optional:

  • sortBy: The column to sort by. Valid values: DisplayName, RunDate, Description. It defaults to DisplayName.

  • sortOrder: The sort order. Valid values: ASC or DESC. It defaults to ASC.

  • idxFrom: The starting index. 0 is the first.

  • idxTo: The ending index (inclusive).

    idxTo must be greater than or equal to idxFrom.

  • dateFrom: the starting date in epoch time since Jan 1, 1970 in milliseconds, inclusive

  • dateTo: the end date in epoch time since Jan 1, 1970 in milliseconds, inclusive

  • state: absent - same as "all"

    • all - return all reports

    • unfinished - only return in-progress ones, subset of "all"

    • finished - return non in-progress ones, subset of "all"

    • success - return successfully finished ones, subset of "finished"

    • failed - return failed ones, subset of "finished"

The following logic applies to completed reports:

  • dateFrom/To applies first, if present.

  • sortBy/sortOrder applies second.

  • idxFrom/To applies last, if present.

Here are the filters:

  • filterDisplayName

  • filterDescription

  • filterCreator

  • filterTags

  • filterLOP (OR or AND)

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{"TotalSize":3,
 "Results":[{"ReportID":"3c604da1-9a3e-4c77-bff1-4ceaac9e6b33","DisplayName":"CCC","RunDate":1265213805296},
            {"ReportID":"05b988af-3f03-4c42-b2b1-067e40d3dca7","DisplayName":"DDD","RunDate":1265213805234},
            {"ReportID":"85710ba9-8980-40d8-b796-72c854f473fd","DisplayName":"Role Assignment Report Daily","RunDate":1265217393687}
           ]
}

TotalSize reflects the amount without idxFrom/To applied.

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"InvalidInput"}
    },
   "Reason":{"Text":"Invalid sortOrder url parameter specified: ASCENDING.  Valid values are ASC, DESC"}
  }
}

Here are the fault codes:

  • 400 InvalidInput: Various input problems (Sender)

  • 500 InternalError: Server problem (Receiver)

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.18 GET /rpt/reports/<report id>

Gets a completed report.

Retrieves detailed information on the report specified.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
  "Name":"My Resource_20100110142266",
  "InProgress":false,
  "failed":false,
  "DisplayName":"My Resource0",
  "RunDate":1264827600000,
  "PluginParameterDefinitions":
      [{"Type":"String",
      "DisplayName":"PLUGIN_DIRECTORY",
      "InternalName":"PLUGIN_DIRECTORY",
      "Description":"Location of plugin files",
      "IsForPrompting":"0"}
     ],
  "Email":
    {"To":
      ["allison blake <ablake@novell.com>",
       "chip nano <cnano@novell.com>"],
     "Cc":
       ["fred stats <fstats@novell.com>",
       "bob bender <bbender@novell.com>"],
     "Subject":"Please verify",
     "Message":"See attached report."}
  "RunBy":
    {"Value":<run_user_id>,
     "DisplayName":"Fred Stats",
    },
}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Here are the fault codes:

  • 404 InvalidURI: URI not found (Sender)

  • 500 InternalError: Server problem (Receiver)

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.19 GET /rpt/reports/<report id>/file

Gets the actual report file.

Get the actual report file for the report specified.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format PDF, CSV

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

Content-Disposition: inline; filename="Report_<timestamp>.<file_extension>”
Content-Type: <one of application/pdf and application/csv

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Here are the fault codes:

  • 404 InvalidURI: URI not found (Sender)

  • 500 InternalError: Server problem (Receiver)

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.20 DELETE /rpt/reports/<report id>

Deletes a completed report.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{"GUID":"e3dd599e-0476-4b76-b140-625d51372e79","Status":"OK"}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Here are the fault codes:

  • Sender

    • 404 InvalidURI: URI not found

    • 400 InvalidInput: the report to be deleted is in progress

  • Receiver

    • 500 InternalError: Server problem

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.21 GET /rpt/calendar

Gets upcoming runs.

Retrieves detailed information on the report specified. Returns an array of planned runs in running order, optionally filtered. There are two exclusive filter sets which cannot be applied together in one request. Both are optional.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

There are no required parameters:

The following parameters are optional:

  • dateFrom (inclusive) /dateTo (inclusive) defines the time range. Either of them is optional. The value must be specified as POSIX milliseconds.

  • upcomingRuns defines up to how many planned runs will be returned. Must be an integer greater than 0.

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{ “Entries” : [
  {"ScheduleDisplayName":"My Resource2",
   "definitionName":"myResource2",
   “definitionDisplayName”: “My Resource2”,
   "RunDate":1264827600000,
   "ScheduleID":"e3dd599e-0476-4b76-b140-625d51372e79"},
more...
])

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Here are the fault codes:

  • Sender

    • 400 InvalidInput: Various input problems

  • Receiver

    • 500 InternalError: Server problem

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.22 GET /rpt/buildinfo

Gets information about the build.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this:

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{"rev":"630","date":"Jan 30, 2010 9:31:23 AM","user":"bsiegal","version":"1.0"}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.23 GET /rpt/collectors

Gets collectors.

Retrieves a list of systems that data is being collected on localized by server-side.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this:

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
  "TotalSize":10,
  "Collector":[
    {"ID":"idvault",
    "DisplayName":"Identity Vault",
    "Link":"collector/idvault"},
    {"ID":"sentinel",
    "DisplayName":"Sentinel Event System",
    "Link":"collector/sentinel"},
more...
  ]
}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.24 GET /rpt/collectors/<collector id>/config

Gets the configuration of the specified data collector.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
  "TotalSize":10,
  "Collector":[
    {"ID":"idvault",
    "DisplayName":"Identity Vault",
    "Link":"collector/idvault"},
    {"ID":"sentinel",
    "DisplayName":"Sentinel Event System",
    "Link":"collector/sentinel"},
more...
  ]
}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.25 GET /rpt/rptusers/<token>

Gets a reporting user’s information.

Retrieves information such as name, email address, and so forth.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
  "DN": …,
  "Name":"...",
  "Locale":"...",
  "Email":...
}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Here are the fault codes:

  • Sender

    • 401: Query tokens other than owned is not allowed

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.26 GET /rpt/rptusers/user

Gets the current user’s information and redirects the client to /rpt/rptusers/<token>.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 307 Temporary Redirect

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.27 GET /rpt/idmusers

Get a list of users to report on sorted by display expression with localized display expression (for example, if in English FirstName LastName, else if in Chinese LastName FirstName).

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

The following optional parameter may be specified:

  • filter: filter=FirstName LIKE a% OR LastName LIKE a%

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

[ 
  {
     “ID”: “13413”, 
     “Value”: “Angie Chung”,
     “Link”: “/rpt/idmusers/13413”
  },
  {
     “ID”: “23413”, 
     “Value”: “Allison Blake”,
     “Link”: “/rpt/idmusers/23413”
  },
  more...
]

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.28 GET /rpt/idmusers/<idmuser id>

Get details on the specified user.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
  “ID”: “13413”, 
  “Value”: “Angie Chung”,
  “Link”: “/rpt/idmusers/13413/attributes”,
what else?
}

Status Code: 4xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.29 GET /rpt/idmroles

Get a list of of roles TO REPORT ON, sorted by localized Display Name.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

The following optional parameter may be specified:

  • filter: filter=DisplayName LIKE a%

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

[ 
  {
     “ID”: “adsa13413”, 
     “Value”: “Doctor”,
     “Link”: “/rpt/idmroles/adsa13413”
  },
  {
     “ID”: “2341sdf3”, 
     “Value”: “Nurse”,
     “Link”: “/rpt/idmroles/2341sdf3”
  },
  more...
]

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.30 GET /rpt/idmroles/<idmrole id>

Gets details on the specified role.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
     “ID”: “adsa13413”, 
     “Value”: “Doctor”,
what else?
}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.31 GET /rpt/idmresources

Get a list of of resources to report on, sorted by localized Display Name.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

The following optional parameter may be specified:

  • filter: filter=DisplayName LIKE a%

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

[ 
  {
     “ID”: “16h3413”, 
     “Value”: “Resources A”,
     “Link”: “/rpt/idmresources/16h3413”
  },
  {
     “ID”: “23ba413”, 
     “Value”: “Resources B”,
     “Link”: “/rpt/idmresources/23ba413”
  },
  more...
]

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.32 GET /rpt/idmresources/<idmresource id>

Retrieves details for a specified resource.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
     “ID”: “adsa13413”, 
     “Value”: “Doctor”,
what else?
}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.33 GET /rpt/idmentitlements

Gets a list of of entitlements to report on, sorted by localized Display Name.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

The following optional parameter may be specified:

  • filter: filter=DisplayName LIKE a%

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

[ 
  {
     “ID”: “13aa413”, 
     “Value”: “Entitlement A”,
     “Link”: “/rpt/idmentitlements/13aa413”
  },
  {
     “ID”: “2sd3413”, 
     “Value”: “Entitlement B”,
     “Link”: “/rpt/idmentitlements/2sd3413”
  },
  more...
]

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.34 GET /rpt/idmentitlements/<idmentitlement id>

Retrieves details on a specified entitlement.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
     “ID”: “13aa413”, 
     “Value”: “Entitlement A”,
what else?
}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.35 GET /rpt/idmteams

Gets a list of of teams to report on, sorted by localized Display Name.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

The following optional parameter may be specified:

  • filter: filter=DisplayName LIKE a%

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

[ 
  {
     “ID”: “13354413”, 
     “Value”: “Jake Prov Team”,
     “Link”: “/rpt/idmteams/13354413”
  },
  {
     “ID”: “2dsvs”, 
     “Value”: “Flora Role Team”,
     “Link”: “/rpt/idmteams/2dsvs”
  },
  more...
]

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.36 GET /rpt/idmteams/<idmteam id>

Retrieves details on a specified team.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
     “ID”: “13354413”, 
     “Value”: “Jake Prov Team”,
     “Link”: “/rpt/teams/13354413/members”
}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.37 GET /rpt/conf

Get global configuration of the core server.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{
"SmtpHost":"...",
"SmtpPort":465,
"SmtpAuth":true,
"SmtpUser":"...",
"SmtpPass":"noguessing",
"SmtpSsl":true,
"DefaultEmail":"test@novell.com",
"ReportFolder":"/home/alex",
"RetentionInterval":1,
"RetentionUnit":"MONTH",
"NameOrder":"default|$FN $LN",
"ExpectedDataCollectionTime":3600000}

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Here are the fault codes:

  • Sender

    • 401: Query tokens other than owned is not allowed

  • Receiver

    • 500 InternalError: Server problem

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.38 POST /rpt/conf

Sets the global configuration for the core server.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

{"SmtpHost":"...", 
"SmtpPort":465, 
"SmtpAuth":true, 
"SmtpUser":"...", 
"SmtpPass":"noguessing", 
"SmtpSsl":true, 
"DefaultEmail":"test@novell.com", 
"ReportFolder":"/home/alex", 
"RetentionInterval":1, 
"RetentionUnit":"week", 
"NameOrder":"default|$FN $LN", 
"ExpectedDataCollectionTime":3600000}

Response

None

Status Code: 200 OK

Status Code: 4xx/5xx

Here is the payload:

{"Fault":{
   "Code":{"Value":"Sender",
           "Subcode":{"Value":"?"}
    },
   "Reason":{"Text":?}
  }
}

Here are the fault codes:

  • Sender

    • 400 InvalidInput: Various input problems

    • 401: Query tokens other than owned is not allowed

  • Receiver

    • 500 InternalError: Server problem

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.39 GET /locales/default

Gets the default locale from the core server.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{"DefaultLocale":"en_us"}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API

13.4.40 GET /locales/supported

Sets the global configuration for the core server.

This operation requires authentication. You need to set the Authorization request header for this operation, giving it a type of X-OPAQUE, as well as the token you received during the login operation. It looks like this: 

Authorization: X-OPAQUE <token>

Format JSON, XML

URL Parameters

None

Data to Send

None

Response

None

Status Code: 200 OK

Here is the payload:

{"SupportedLocales":[da,de,en,es,fr,it,ja,nl,pt,ru,sv,zh_cn,zh_tw]}

Status Code: 401 Unauthorized

Here is the payload:

{"Fault":
  {"Code":
    {"Value":"Sender",
     "Subcode":
       {"Value":"InvalidAuthHeader"}
     },
   "Reason":
     {"Text":"User carries unrecognized/expired/invalid authentication token."}
   }
}

Here are the fault subcodes:

  • InvalidAuthHeader: Bad token or expired token

  • NoAuthHeader: Token not carried

  • NoPrivilege: Token valid but user is not a reporting administrator, and therefore has no access to the REST API