Initializing help system before first use

Portation resources

Operation Description
GET /api/portations

Get all undismissed portations
POST /api/portations/dismissed

Dismiss portations
POST /api/portations/exports

Create an export
GET /api/portations/exports/{id}

Get an export
GET /api/portations/exports/{id}/file

Get the binary data of an export
GET /api/portations/files

Get all portation files
POST /api/portations/imports

Create an import
GET /api/portations/imports/{id}

Get an import

GET /api/portations

Get all undismissed portations

Get all portations visible to the current user that have not previously been dismissed.

Request Parameters

Name Description Type Data Type
page

Number of the page, starting at zero

 query integer (int32)
size

Number of elements per page

 query integer (int32)

Responses

200 OK

The page of portations

Content-Type application/vnd.com.fico.xpress.insight.v2+json

PageOfPortation

POST /api/portations/dismissed

Dismiss portations

Dismiss portations identified by the provided IDs.

Request Body

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Array of string

Responses

204 No Content

The portations have been dismissed

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Empty response body

404 Not Found

A portation does not exist or the user does not have access to it

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

POST /api/portations/exports

Create an export

Create an export from the provided ExportRequest. The created export will record the progress and outcome of exporting the source described by the request.

Request Body

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ExportRequest

Responses

201 Created

Export created

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Export

Location

The URL of the created resource

 string
403 Forbidden

Access denied

422 Unprocessable Entity

Attempting to export an unsupported object type (not an app, folder or scenario)

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-422",
        "desc": "Unprocessable Entity",
        "innerError": {
            "code": "FICO-Platform-Validation-InvalidValue",
            "desc": "Entity processing failed",
            "message": "Entity processing failed"
        },
        "message": "Unprocessable Entity",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/portations/exports/{id}

Get an export

Get an export by ID.

Request Parameters

Name Description Type Data Type
id

The ID of the export

 path string (uuid) required

Responses

200 OK

The export

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Export

404 Not Found

The export does not exist or the user does not have access to it

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/portations/exports/{id}/file

Get the binary data of an export

Get the binary data of the export identified by the provided ID.

Request Parameters

Name Description Type Data Type
id

The ID of the export

 path string (uuid) required

Responses

200 OK

Binary stream of the file contents

Content-Type application/vnd.com.fico.xpress.insight.v2+octet-stream

string (binary)

404 Not Found

The portation file does not exist or the user does not have access to it

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
Content-Type application/vnd.com.fico.xpress.insight.v2+octet-stream

Empty response body

GET /api/portations/files

Get all portation files

Get all portation files available for import to the server.

Request Parameters

Name Description Type Data Type
page

Number of the page, starting at zero

 query integer (int32)
size

Number of elements per page

 query integer (int32)

Responses

200 OK

The portation files

Content-Type application/vnd.com.fico.xpress.insight.v2+json

PageOfPortationDirectory

403 Forbidden

Access denied

POST /api/portations/imports

Create an import

Create an import from the provided insight file. This will record the progress and outcome of importing the supplied file.

Request Body

Content-Type multipart/form-data

Properties

importUploadRequest: required

Options controlling the import

insightFile: string (binary) required

The insight file to be imported

Responses

201 Created

Import created

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Import

Location

The URL of the created resource

 string
403 Forbidden

Access denied

413 Request Entity Too Large

The file to import exceeds the maximum insight file upload size

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-413",
        "desc": "Payload Too Large",
        "innerError": {
            "code": "FICO-Platform-Validation-FileTooLarge",
            "desc": "Insight file too large",
            "message": "File larger than 300 MB cannot be imported via upload. Try importing via file system."
        },
        "message": "Payload Too Large",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
422 Unprocessable Entity

Invalid import type, invalid target or unsupported security option for the supplied import type

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-422",
        "desc": "Unprocessable Entity",
        "innerError": {
            "code": "FICO-Platform-Validation-InvalidValue",
            "desc": "Entity processing failed",
            "message": "Entity processing failed"
        },
        "message": "Unprocessable Entity",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/portations/imports/{id}

Get an import

Get an import by ID.

Request Parameters

Name Description Type Data Type
id

The ID of the import

 path string (uuid) required

Responses

200 OK

The import

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Import

404 Not Found

The import did not exist or the user did not have access to it

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

ErrorDetail: object

An error detail

Properties

code: string

The unique code for this error

Example: 
"FICO_PLATFORM_VALIDATION_INVALID_VALUE"
desc: string

A description of this error for client information, not intended for display to the end user

Example: 
"Conflict"
message: string

A message providing further information which may be displayed to the end user

Example: 
"Conflict"
target: string

An identifier to help the client locate the error. Typically a JSON property name.

timestamp: string (date-time)

When the error was first detected

ErrorResponse: object

An error response containing fault or error information

Properties

error:

The top level error

Export: object

Contains the status and location of an export.

Properties

dismissed: boolean

True indicates this portation has been dismissed by the owner.

Example: 
false
downloadUrl: string (uri)

The download url of this export

Example: 
"/api/portations/exports/9b70bd59-9499-4848-9b5b-75aaa0c26f35/file"
errorMessages: string[]

The error messages produced by this portation

Array of string
filename: string

The filename for this portation

Example: 
"MyFile.insight"
finished: string (date-time)

When this portation finished

id: string (uuid)

The ID of this export

Example: 
"02864266-a4a8-a1bc-fd79-bd98e09b5690"
includeFoldersAndScenarios: boolean

The filter to indicate whether folders and scenario are included as part of this export or not. This is applicable only for an app export

Example: 
false
infoMessages: string[]

The info messages produced by this portation

Array of string
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this export

Example: 
"My export"
objectType: string , one of { EXPORT }
owner:

The user that owns this portation

parent:

The parent of this portation. This is populated when this portation belongs to another. For example when importing an insight file which contains many apps then each app import will be parented by the original import portation.

path: string

The path for this export relative to the configured portation directory.

Example: 
"exports/MyExport.insight"
reference:

The reference of the item (app, folder or scenario) being ported

started: string (date-time)

When this portation started

status: string , one of { ERROR , MIGRATING , PORTING , QUEUED , SUCCESS }

The status of this portation

url: string (uri)

The URL of this export

Example: 
"/api/portations/exports/02864266-a4a8-a1bc-fd79-bd98e09b5690"

ExportRequest: object

Properties

includeFoldersAndScenarios: boolean

Filter to indicate whether to include folders and scenario as part of an app export. This is not required for a folder or a scenario export

Example: 
false
source:

Reference to the item (app, folder or scenario) to be exported

Import: object

Contains the status and location of an import.

Properties

dismissed: boolean

True indicates this portation has been dismissed by the owner.

Example: 
false
errorMessages: string[]

The error messages produced by this portation

Array of string
filename: string

The filename for this portation

Example: 
"MyFile.insight"
finished: string (date-time)

When this portation finished

id: string (uuid)

The ID of this import

Example: 
"816db222-428d-6802-7e92-4dde3c7e3059"
importType: string , one of { APP , FOLDER_OR_SCENARIO , REPOSITORY }

Type of import to perform with the supplied file.

Example: 
"APP"
infoMessages: string[]

The info messages produced by this portation

Array of string
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this import

Example: 
"My import"
objectType: string , one of { IMPORT }
owner:

The user that owns this portation

parent:

The parent of this portation. This is populated when this portation belongs to another. For example when importing an insight file which contains many apps then each app import will be parented by the original import portation.

reference:

The reference of the item (app, folder or scenario) being ported

security: string , one of { ORIGINAL , PRIVATE }

Controls the security of imported assets

Example: 
"ORIGINAL"
started: string (date-time)

When this portation started

status: string , one of { ERROR , MIGRATING , PORTING , QUEUED , SUCCESS }

The status of this portation

target:

The reference to the parent of the imported scenario or folder. This will not be populated for an app import

url: string (uri)

The URL of this import

Example: 
"/api/portations/imports/816db222-428d-6802-7e92-4dde3c7e3059"

ImportUploadRequest: object

Properties

importType: string , one of { APP , FOLDER_OR_SCENARIO , REPOSITORY }

Type of import to perform with the supplied file.

Example: 
"APP"
security: string , one of { ORIGINAL , PRIVATE }

Controls the security of imported assets

Example: 
"ORIGINAL"
target:

The reference to the target item (app or folder) to which a folder or a scenario is to be imported. This will not be needed for an app or repository import

InnerError: object

More specific error information

Properties

code: string

The unique code for this error

Example: 
"FICO-Platform-Validation-FileTooLarge"
desc: string

A description of this error for client information, not intended for display to the end user

Example: 
"Attachment upload too large"
innerError:

More specific error information

message: string

A message providing further information which may be displayed to the end user

Example: 
"Files larger than 300 MB cannot be uploaded as attachments."

OuterError: object

The top level error

Properties

code: string , one of { FICO-Platform-Http-400 , FICO-Platform-Http-404 , FICO-Platform-Http-409 , FICO-Platform-Http-413 , FICO-Platform-Http-422 , FICO-Platform-Http-423 , FICO-Platform-Http-429 , FICO-Platform-Http-500 , FICO-Platform-Http-502 , FICO-Platform-Http-503 }

The unique code for this error

Example: 
"FICO-Platform-Http-409"
desc: string

A description of this error for client information, not intended for display to the end user

Example: 
"Conflict"
details: object[]

Details about specific errors that led to this reported error

Array of ErrorDetail
innerError:

More specific error information

message: string

A message providing further information which may be displayed to the end user

Example: 
"Conflict"
parentId: string

An OpenTracing parent-span ID

Example: 
"0020000000000001"
spanId: string

An OpenTracing span ID

Example: 
"b2fb4a1d1a96d312"
timestamp: string (date-time)

When the error was first detected

traceId: string

An OpenTracing trace ID

Example: 
"463ac35c9f6413ad48485a3953bb6125"

PageOfPortation: object

A page containing a subset of content which can be paginated through

Properties

content: object[]

The items in this page of results

Array of Portation
first: boolean

Whether this is the first page

Example: 
false
last: boolean

Whether this is the last page

Example: 
true
number: integer (int32)

The page number, starting at 0

Example: 
4
numberOfElements: integer (int32)

The number of elements in this page of results

Example: 
18
size: integer (int32)

The number of results per page

Example: 
20
sort:

The sort order applied to the results

totalElements: integer (int32)

The total number of elements in all the pages

Example: 
98
totalPages: integer (int32)

The total number of pages

Example: 
5

PageOfPortationDirectory: object

A page containing a subset of content which can be paginated through

Properties

content: object[]

The items in this page of results

Array of PortationDirectory
first: boolean

Whether this is the first page

Example: 
false
last: boolean

Whether this is the last page

Example: 
true
number: integer (int32)

The page number, starting at 0

Example: 
4
numberOfElements: integer (int32)

The number of elements in this page of results

Example: 
18
size: integer (int32)

The number of results per page

Example: 
20
sort:

The sort order applied to the results

totalElements: integer (int32)

The total number of elements in all the pages

Example: 
98
totalPages: integer (int32)

The total number of pages

Example: 
5

Portation: object

Contains the status and location of a portation.

Properties

dismissed: boolean

True indicates this portation has been dismissed by the owner.

Example: 
false
errorMessages: string[]

The error messages produced by this portation

Array of string
filename: string

The filename for this portation

Example: 
"MyFile.insight"
finished: string (date-time)

When this portation finished

id: string (uuid)

The ID of this reference

infoMessages: string[]

The info messages produced by this portation

Array of string
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this reference

Example: 
"name"
objectType: string , one of { EXPORT , IMPORT }
owner:

The user that owns this portation

parent:

The parent of this portation. This is populated when this portation belongs to another. For example when importing an insight file which contains many apps then each app import will be parented by the original import portation.

reference:

The reference of the item (app, folder or scenario) being ported

started: string (date-time)

When this portation started

status: string , one of { ERROR , MIGRATING , PORTING , QUEUED , SUCCESS }

The status of this portation

url: string (uri)

The URL of this reference

PortationDirectory: object

Describes the location and contents of a directory within the configured portation path.

Properties

files: object[]

The portation files present in this directory

Array of PortationFile
name: string

The directory name

Example: 
"exports"
path: string

The directory path, relative to the configured portation path

Example: 
"/exports"

PortationFile: object

Describes the location and attributes of a portation file.

Properties

filename: string

The filename

Example: 
"MyExport.insight"
lastModified: string (date-time)

When the file was last modified

path: string

The file path, relative to the configured portation path

Example: 
"/exports/MyExport.insight"
size: integer (int64)

The file size in bytes

ReferenceUser: object

The basic details of a user

Properties

id: string (uuid)

The ID of this user

Example: 
"0013ebae-4d4c-793c-ffec-1451b28ba2f9"
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this user

Example: 
"My user"
objectType: string , one of { USER }
url: string (uri)

The URL of this user

Example: 
"/api/admin/users/0013ebae-4d4c-793c-ffec-1451b28ba2f9"

Sort: object

Details of how paged results were sorted

Properties

empty: boolean

True if there are no results

Example: 
false
sorted: boolean

True if the results are sorted

Example: 
false
unsorted: boolean

True if the results are not sorted

Example: 
false
Parent Topic Insight 5 REST API

© 2001-2022 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.