Create CSV Report With Manifest

Create your authorization token

Generate an API Token via Frontegg Dashboard UI:

Navigate to http://<instance-id>.illustria.io
Login
Click on your avatar and click on "Profile".
Click on "API Tokens" tab. If you want to be notified via email later on when the report is ready, please choose "Personal Tokens".
Generate your token, by adding a description and an "Admin" role.
Copy the Client ID and Secret Key, as we will use them in the next step.
Create your JWT token. Use Frontegg vendor authentication API:

Parameter	Type	Explanation
instance-id	string	This parameter will be given by illustria team.
your-client-id	string
your-secret-key	string

curl --request POST \
   --url https://illustria.frontegg.com/identity/resources/auth/v1/api-token \
   --header 'accept: application/json' \
   --header 'content-type: application/json' \
   --data '
  {
    "clientId": "<your-client-id>",
    "secret": "<your-secret-key>"
  }
  '

info

Make sure to save the accessToken value from the response as this will be <your-authorization-token> in the following steps.

Upload manifest file

Upload the manifest file to the system. The parameters for this case are:

Parameter	Type	Explanation
instance-id	string	This parameter will be given by illustria team.
Authorization	string	Use the parameter from previous step.
path-to-manifest-file	string	The location of your manifest file.

Example code

curl --request POST \
  --url https://<instance-id>.illustria.io/artifacts/upload \
  --header 'Authorization: Bearer <your-authorization-token>' \
  --header 'Content-Type: multipart/form-data' \
  --form files=@<path-to-manifest-file>

info

The response of this request is the artifact-id.
Make sure you keep it as this is the identifier of your file in the system.

Generate the report and get the report ID

Once you have the artifact-id you can generate the report:

The GraphQL query:

mutation GenerateRisksReportLocalDev($reportType: String!, $packageManager: String!, $artifactId: String!, $projectName: String!, $notify: Boolean!) {
    generateReportFromArtifactId(
        reportType: $reportType
        packageManager: $packageManager
        artifactId: $artifactId
        projectName: $projectName
        notify: $notify
    ) {
        __typename
        ... on GQLReport {
            id_
            status
        }
    }
}

With the following query parameters:

Parameter	Type	Explanation
reportType	string	Default value "detailed"
package-manager	string	Supports the following: "npm" or "pip"
artifact-id	string	The id received when executing the upload command.
project-name	string	The project name of your choice.
notify	boolean	Send an email to notify the user when the report is ready. Default value false.

{
    "reportType": "detailed",
    "packageManager": <package-manager>,
    "artifactId": <artifact-id>,
    "projectName": <project-name>,
    "notify": false
}

Example code

  curl --request POST \
  --url https://<instance-id>.illustria.io/reporter/graphql \
    --header 'Authorization:  Bearer <your-authorization-token>' \
    --header 'Content-Type: application/json' \
  --data '{"query":"mutation GenerateRisksReportLocalDev($reportType: String!, $packageManager: String!, $artifactId: String!, $projectName: String!, $notify: Boolean!) {\n\tgenerateReportFromArtifactId(\n\t\treportType: $reportType\n\t\tpackageManager: $packageManager\n\t\tartifactId: $artifactId\n\t\tprojectName: $projectName\n\t\tnotify: $notify\n\t) {\n\t\t__typename\n\t\t... on GQLReport {\n\t\t\tid_\n\t\t\t\tstatus\n\t\t}\n\t}\n}\n","operationName":"GenerateRisksReportLocalDev","variables":{"reportType":"detailed" ,"packageManager": <package-manager>,"artifactId": <artifact-id>,"projectName": <project-name>,"notify": false}}'

info

If the artifact id is inserted correctly, you should get the report information, including its status.
In case of an error, the error code and message will be raised.

In the response of this request we can find the report-id. Save it for the next step.

danger

If notify is set to true, and the API token was generated through the "API Tokens" option in the first step (and not through the "Personal Tokens"), the report generation flow will fail.

Check report status and download CSV Artifact

With the report-id the report generation process status can be monitored. Once the status is set to finished, the CSV artifact will be available to download.

info

The possible statuses for a report are: "accepted", started", "error" and "finished".

The GraphQL query:

curl --request POST \
  --url https://<instance-id>.illustria.io/graphql \
  --header 'Authorization: Bearer <your-authorization-token>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"query Fetch ($recordIds: [String!]!, $filters: GQLFilterParams){\n    fetch (recordType: REPORTER_REPORT, recordIds: $recordIds, filters: $filters) {\n\t\t\t\t__typename\n        ... on GQLFetchResults {\n            records {\n\t\t\t\t\t\t\t\t\t\t\t\t\t... on GQLReport {\n\t\t\t\t\t\t\t\t\t\t\t\t\t\tid_\n\t\t\t\t\t\t\t\t\t\t\t\t\t\tstatus\n\t\t\t\t\t\t\t\t\t\t\t\t\t\tartifactsDict{\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\tcsv{\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\tid_\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\tpdf{\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\tid_\n\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t}\n            }\n        }\n    }\n\t}\n}\n}","operationName":"Fetch","variables":{"recordIds":["<report-id>"],"filters":{"searchValue":"","page":0,"limit":1,"orderDir":"asc","orderBy":[]}}}'

With the following query parameters:

Parameter	Type	Explanation
recordIds	List[String]	List of one string element. This element is the report id from previous step.
report-id	string	This was retrieved in the previous step.
filters	Dictionary[String, Union[int, String]]	Set to the default value. No need to make any changes.

{
    "recordIds": List[report-id],
    "filters": {"searchValue":"","page":0,"limit":1,"orderDir":"asc","orderBy":[]}
}

info

In the returned response we can find the artifactsDict key, which holds the relevant CSV artifact ID. This key can be found in the records list. Save this ID as the artifact-id of the CSV report, and use it in the next step to download it.

Download the CSV file

Parameter	Type	Explanation
artifact-id	string	The CSV artifact ID received from the previous step.
report_result	string	The title assigned to the compressed file directory wherein the reports are stored.

Example code

curl --request GET \
  --url 'https://<instance-id>.illustria.io/artifacts/download?artifact_id=<artifact-id>' \
  --header 'Authorization: Bearer <your-authorization-token>' \
  -o report_results

info

Please note that we are anticipating the download and saving of a zip archive file, which should be named as "report_results".

Extract the CSV results file

The reports are stored in a zip directory. The following command extracts the CSV file from the zip archive and stores it as a new file called "report_results_output.csv".

unzip -p report_results '*.csv' > report_results_output.csv

Create CSV Report With Manifest

Create your authorization token​

Generate an API Token via Frontegg Dashboard UI:​

Upload manifest file​

Example code​

Generate the report and get the report ID​

Example code​

Check report status and download CSV Artifact​

The GraphQL query:​

Download the CSV file​

Example code​

Extract the CSV results file​

Create your authorization token

Generate an API Token via Frontegg Dashboard UI:

Upload manifest file

Example code

Generate the report and get the report ID

Example code

Check report status and download CSV Artifact

The GraphQL query:

Download the CSV file

Example code

Extract the CSV results file