Skip to main content
Cartegraph Campus

Attachments for REST API

This feature may not be available in every package. Not sure if you have this feature or you want to learn more about it? Send us a message at support@cartegraph.com.

Cartegraph's API is a licensed product that requires a purchase and verified ownership before production use.

The methods for attachments allows a user to retrieve, create, delete or update an attachment file associated to a cgAttachmentsClass record. These methods only allow for interaction with one attachment record\file at a time.

Linked Attachments

These methods generally do not support attachments marked as linked attachments. A user may read, create, update, or delete linked attachments using the Business Object methods on cgAttachmentsClass records. Here you can get or set the Attachment field value, which in the case of linked attachments is a link (For example, AttachmentField has a value of http://www.{somewebsite}.com/MyAttachment.jpg) and get or set the LinkedField value, which in the case of linked attachments has a value of true.

Get (Read)

  • Purpose: Retrieve a file associated to a specific attachment record.
  • HTTP Method: GET
  • URL
    • https://yourserver.com/cartegraph/api/v1/attachments/{className}/{id}
  • URL Parameters
    • className - required - Cartegraph class name (for example, cgSigns_cgAttachmentsClass)
    • id - required - Oid of the attachment record

Example Requests

Get the file associated to the Sign Attachment record with Oid 435560664:

GET https://yourserver.com/cartegraph/api/v1/attachments/cgSigns_cgAttachmentsClass/435560664

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains the binary of the attachment file requested.
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name/Oid in the URL
    • Invalid URI path. {uriPath} has more URI segments than is allowed.
      • The URL contains more than the valid number of URI segments for that given URI.
      • In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the URL specification in order to view URL examples with valid numbers of segments.
      • Example: For a GET, /cgSignsClass/651592699/cgSigns_cgAttachmentsClass/2131404296 -- There are more than two segments (in this example, /{className}/{id}/{className}/{id}).
    • {className} is not a valid class name
      • An invalid class name was entered in the URL
      • Example: cgBlah_cgAttachmentsClass/1234 -- cgBlah_cgAttachmentsClass does not exist in the OMS database so it is invalid.
    • {className} is not an attachments recordset.
      • The class name specified is not for an attachments recordset
    • Oid is required
      • This message is given when an Oid is missing in the URL
    • Unable to convert {id} to an oid
      • An invalid value was entered for an Oid in the URL
      • Example: /cgSigns_cgAttachmentsClass/AB1234 -- Oids are numbers and cannot contain letters.
    • Cannot find a {className} record with an oid of {id}.
      • The associated attachment record could not be found
    • Attachment record is a linked attachment.
      • The associated attachment record is for a linked attachment, which this method does not support. See the section on Linked Attachments for more details
  • 403 Forbidden
    • {attachmentFieldValue}: File access denied.
      • Could not access the directory location or file specified via the Attachment field's value
  • 404 Not Found
    • {attachmentFieldValue}: File not found.
      • Could not find the directory location or file specified via the Attachment field's value
  • 500 Internal Server Error
    • An error has occurred while processing the transaction. More details can be found in the Error log within OMS.

Get (Read) Primary Attachment

  • Purpose: Retrieve a file set as the primary attachment on a record.
  • HTTP Method: GET
  • URL:
    • https://yourserver.com/cartegraph/api/v1/attachments/primary/{className}/{id}
  • URL Parameters:
    • className - required - Cartegraph class name (for example, cgSignsClass)
    • id - required - Oid of the record

Example Requests

Get the primary attachment file associated to the Sign record with Oid 435560664:

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/cgSignsClass/435560664

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains the binary of the attachment file requested.
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name/Oid in the URL
    • Invalid URI path. {uriPath} has more URI segments than is allowed.
      • The URL contains more than the valid number of URI segments for that given URI.
      • In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the URL specification in order to view URL examples with valid numbers of segments.
      • Example: For a GET, /cgSignsClass/651592699/cgSigns_cgAttachmentsClass/2131404296 -- There are more than two segments (in this example, /{className}/{id}/{className}/{id}).
    • {className} is not a valid class name
      • An invalid class name was entered in the URL
      • Example: cgBlahClass/1234 -- cgBlahClass does not exist in the OMS database so it is invalid.
    • {className} does not contain an attachments recordset.
      • The class name specified does not contain a child attachments recordset
    • Oid is required
      • This message is given when an Oid is missing in the URL
    • Unable to convert {id} to an oid
      • An invalid value was entered for an Oid in the URL
      • Example: /cgSignsClass/AB1234 -- Oids are numbers and cannot contain letters.
    • Cannot find a {className} record with an oid of {id}.
      • The requested record could not be found
    • No primary attachment set for {className} record with an oid of {id}.
      • The requested record does not have a primary attachment set
    • Attachment record is a linked attachment.
      • The associated attachment record is for a linked attachment, which this method does not support. See the section on Linked Attachments for more details
  • 403 Forbidden
    • {attachmentFieldValue}: File access denied.
    • Could not access the directory location or file specified via the Attachment field's value
  • 404 Not Found
    • {attachmentFieldValue}: File not found.
      • Could not find the directory location or file specified via the Attachment field's value
  • 500 Internal Server Error
    • An error has occurred while processing the transaction. More details can be found in the Error log within OMS.

GET Thumbnail

  • Purpose: Retrieve a thumbnail image representation of a file associated to a specific attachment record.
  • Behavior Summary: If the attachment file is a supported image file type for scaling the original image (bmp, jpg, jpeg, png, and gif), thumbnail mode will return a scaled version of the original image attachment. If the attachment file is not a supported image file type for scaling the original file, the response will optionally either be JSON that communicates this or a stock Cartegraph thumbnail image.
    • If the original image is larger than 400 x 400 pixels the thumbnail is returned as a scaled version 400 x 400 pixels otherwise a scaled version of the image is returned based on its current height and width. In either case the aspect ratio of the original image is maintained. Any remaining space around the image will get padded with transparency.
  • HTTP Method: GET
  • URL:
    • https://yourserver.com/cartegraph/api/v1/attachments/thumbnail/{className}/{id}
  • URL Parameters:
    • className - required - Cartegraph class name (for example, cgSigns_cgAttachmentsClass)
    • id - required - Oid of the attachment record
  • Optional Parameters:
    • useDefaultThumbnails - A Boolean value (accepts the values true and false) to specify if a stock Cartegraph thumbnail image should be returned or if JSON should be returned in the following cases:
      • The attachment file is not found
      • The attachment file is not one of the supported image file types for scaling the original file
      • The attachment is a linked attachment
    • If the value is true, a stock Cartegraph thumbnail image will be returned in the above cases. If the value is false, JSON will be returned. The default value is false if the parameter is omitted

Example Requests and Responses

Request
Get the non-linked attachment, image file associated to the Sign Attachment record with Oid 761601132 as a thumbnail. Will not use default thumbnails (by default):

GET https://yourserver.com/cartegraph/api/v1/attachments/thumbnail/cgSigns_cgAttachmentsClass/761601132

Response

(Scaled version of real image file)

Request
Get the non-linked attachment, image file associated to the Sign Attachment record with Oid 761601132 as a thumbnail. Will use default thumbnails:

GET https://yourserver.com/cartegraph/api/v1/attachments/thumbnail/cgSigns_cgAttachmentsClass/761601132?useDefaultThumbnails=true

Response

(Scaled version of real image file)

Request
Get the non-linked attachment, non-image file associated to the Sign Attachment record with Oid 1137753946 as a thumbnail. Will not use default thumbnails (by default):

GET https://yourserver.com/cartegraph/api/v1/attachments/thumbnail/cgSigns_cgAttachmentsClass/1137753946

Response

{
  "Message": "The file has a file type that cannot be converted into a thumbnail image.",
  "FileExtension": "mp3",
  "IsLinkedAttachment": false
}

Request
Get the non-linked attachment, non-image file associated to the Sign Attachment record with Oid 1137753946 as a thumbnail. Will use default thumbnails:

GET https://yourserver.com/cartegraph/api/v1/attachments/thumbnail/cgSigns_cgAttachmentsClass/1137753946?useDefaultThumbnails=true

Response

(Stock Cartegraph image for non-image files)

Request
Get the non-linked attachment file that cannot be found and is associated to the Sign Attachment record with Oid 1680313388 as a thumbnail. Will not use default thumbnails (by default):

GET https://yourserver.com/cartegraph/api/v1/attachments/thumbnail/cgSigns_cgAttachmentsClass/1680313388

Response

(404 Not Found error; refer to Status Codes Returned and Common Error Messages section)

Request
Get the non-linked attachment file that cannot be found and is associated to the Sign Attachment record with Oid 1680313388 as a thumbnail. Will use default thumbnails:

GET https://yourserver.com/cartegraph/api/v1/attachments/thumbnail/cgSigns_cgAttachmentsClass/1680313388?useDefaultThumbnails=true

Response

(Stock Cartegraph image for file that cannot be found)

Request
Get the linked attachment associated to the Sign Attachment record with Oid 2031028021 as a thumbnail. Will not use default thumbnails (by default):

GET https://yourserver.com/cartegraph/api/v1/attachments/thumbnail/cgSigns_cgAttachmentsClass/2031028021

Response

{
  "Message": "A linked attachment cannot be converted into a thumbnail image.",
  "FileExtension": "",
  "IsLinkedAttachment": true
}

Request
Get the linked attachment associated to the Sign Attachment record with Oid 2031028021 as a thumbnail. Will use default thumbnails:

GET https://yourserver.com/cartegraph/api/v1/attachments/thumbnail/cgSigns_cgAttachmentsClass/2031028021?useDefaultThumbnails=true

Response

(Stock Cartegraph image for linked attachment)

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains the binary of the attachment file requested.
    • The message body may contain JSON if useDefaultThumbnails is set to false and:
      • The attachment file is not found
      • The attachment file is not one of the supported image file types for scaling the original file
      • The attachment is a linked attachment
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name/Oid in the URL
    • Invalid URI path. {uriPath} has more URI segments than is allowed.
      • The URL contains more than the valid number of URI segments for that given URI.
      • In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the URL specification in order to view URL examples with valid numbers of segments.
      • Example: For a GET, /cgSignsClass/651592699/cgSigns_cgAttachmentsClass/2131404296 -- There are more than two segments (in this example, /{className}/{id}/{className}/{id}).
    • {className} is not a valid class name
      • An invalid class name was entered in the URL
      • Example: cgBlah_cgAttachmentsClass/1234 -- cgBlah_cgAttachmentsClass does not exist in the OMS database so it is invalid.
    • {className} is not an attachments recordset.
      • The class name specified is not for an attachments recordset
    • Oid is required
      • This message is given when an Oid is missing in the URL
    • Unable to convert {id} to an oid
      • An invalid value was entered for an Oid in the URL
      • Example: /cgSigns_cgAttachmentsClass/AB1234 -- Oids are numbers and cannot contain letters.
    • Cannot find a {className} record with an oid of {id}.
      • The associated attachment record could not be found
  • 404 Not Found
    • {attachmentFieldValue}: File not found.
    • Could not find the directory location or file specified via the Attachment field's value
  • 500 Internal Server Error
    • An error has occurred while processing the transaction. More details can be found in the Error log within OMS.

Get Primary Attachment Thumbnail

  • Purpose: Retrieve a thumbnail image representation of a file set as the primary attachment on a record.
  • Behavior Summary: If the attachment file is a supported image file type for scaling the original image (bmp, jpg, jpeg, png, and gif), thumbnail mode will return a scaled version of the original image attachment. If the attachment file is not a supported image file type for scaling the original file, the response will optionally either be JSON that communicates this or a stock Cartegraph thumbnail image.
    • If the original image is larger than 400 x 400 pixels the thumbnail is returned as a scaled version 400 x 400 pixels otherwise a scaled version of the image is returned based on its current height and width. In either case the aspect ratio of the original image is maintained. Any remaining space around the image will get padded with transparency.
  • HTTP Method: GET
  • URL:
    • https://yourserver.com/cartegraph/api/v1/attachments/primary/thumbnail/{className}/{id}
  • URL Parameters:
    • className - required - Cartegraph class name (for example, cgSignsClass)
    • id - required - Oid of the record
  • Optional Parameters:
    • useDefaultThumbnails - A Boolean value (accepts the values true and false) to specify if a stock Cartegraph thumbnail image should be returned or if JSON should be returned in the following cases:
      • The attachment file is not found
      • The attachment file is not one of the supported image file types for scaling the original file
      • The attachment is a linked attachment
  • If the value is true, a stock Cartegraph thumbnail image will be returned in the above cases. If the value is false, JSON will be returned. The default value is false if the parameter is omitted

Example Requests and Responses

Request

Get the non-linked attachment, image file set as the primary attachment on the Sign record with Oid 761601132 as a thumbnail. Will not use default thumbnails (by default):

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/thumbnail/cgSignsClass/761601132

Response

(Scaled version of real image file)

Request
Get the non-linked attachment, image file set as the primary attachment on the Sign with Oid 761601132 as a thumbnail. Will use default thumbnails:

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/thumbnail/cgSignsClass/761601132?useDefaultThumbnails=true

Response

(Scaled version of real image file)

Request
Get the non-linked attachment, non-image file set as the primary attachment on the Sign with Oid 1137753946 as a thumbnail. Will not use default thumbnails (by default):

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/thumbnail/cgSignsClass/1137753946

Response

{
  "Message": "The file has a file type that cannot be converted into a thumbnail image.",
  "FileExtension": "mp3",
  "IsLinkedAttachment": false
}

Request
Get the non-linked attachment, non-image file set as the primary attachment on the Sign with Oid 1137753946 as a thumbnail. Will use default thumbnails:

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/thumbnail/cgSignsClass/1137753946?useDefaultThumbnails=true

Response

(Stock Cartegraph image for non-image files)

Request

Get the non-linked attachment file that cannot be found and is set as the primary attachment on the Sign with Oid 1680313388 as a thumbnail. Will not use default thumbnails (by default):

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/thumbnail/cgSignsClass/1680313388

Response

(404 Not Found error; refer to Status Codes Returned and Common Error Messages section)

Request
Get the non-linked attachment file that cannot be found and is set as the primary attachment on the Sign with Oid 1680313388 as a thumbnail. Will use default thumbnails:

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/thumbnail/cgSignsClass/1680313388?&useDefaultThumbnails=true

Response

(Stock Cartegraph image for file that cannot be found)

Request
Get the non-linked attachment file for a record with no primary attachment set on the Sign with Oid 1680313388 as a thumbnail. Will not use default thumbnails (by default):

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/thumbnail/cgSignsClass/1680313388

Response

(400 Bad Request error; refer to Status Codes Returned and Common Error Messages section)

Request
Get the non-linked attachment file for a record with no primary attachment set on the Sign with Oid 1680313388 as a thumbnail. Will use default thumbnails:

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/thumbnail/cgSignsClass/1680313388?useDefaultThumbnails=true

Response

(Stock Cartegraph image for file that cannot be found)

Request
Get the linked attachment set as the primary attachment on the Sign with Oid 2031028021 as a thumbnail. Will not use default thumbnails (by default):

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/thumbnail/cgSignsClass/2031028021

Response

{
  "Message": "A linked attachment cannot be converted into a thumbnail image.",
  "FileExtension": "",
  "IsLinkedAttachment": true
}

Request
Get the linked attachment set as the primary attachment on the Sign with Oid 2031028021 as a thumbnail. Will use default thumbnails:

GET https://yourserver.com/cartegraph/api/v1/attachments/primary/cgSignsClass/2031028021?useDefaultThumbnails=true

Response

(Stock Cartegraph image for linked attachment)

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains the binary of the attachment file requested in the requested dimensions.
    • The message body may contain JSON if useDefaultThumbnails is set to false and:
      • The attachment file is not found
      • The attachment file is not one of the supported image file types for scaling the original file
      • The attachment is a linked attachment
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name/Oid in the URL
    • Invalid URI path. {uriPath} has more URI segments than is allowed.
      • The URL contains more than the valid number of URI segments for that given URI.
      • In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the URL specification in order to view URL examples with valid numbers of segments.
      • Example: For a GET, /cgSignsClass/651592699/cgSigns_cgAttachmentsClass/2131404296 -- There are more than two segments (in this example, /{className}/{id}/{className}/{id}).
    • {className} is not a valid class name
      • An invalid class name was entered in the URL
      • Example: cgBlahClass/1234 -- cgBlahClass does not exist in the OMS database so it is invalid.
    • {className} does not contain an attachments recordset.
      • The class name specified does not contain a child attachments recordset
    • Oid is required
      • This message is given when an Oid is missing in the URL
    • Unable to convert {id} to an oid
      • An invalid value was entered for an Oid in the URL
      • Example: /cgSignsClass/AB1234 -- Oids are numbers and cannot contain letters.
    • Cannot find a {className} record with an oid of {id}.
      • The associated attachment record could not be found
    • No primary attachment set for {className} record with an oid of {id}.
      • The requested record does not have a primary attachment set
  • 404 Not Found
    • {attachmentFieldValue}: File not found.
      • Could not find the directory location or file specified via the Attachment field's value
  • 500 Internal Server Error
    • An error has occurred while processing the transaction. More details can be found in the Error log within OMS.

Post (Create)

  • Purpose: Upload a file and associate it to an auto-created attachment record.
  • HTTP Method: POST
  • URL:
    • https://yourserver.com/cartegraph/api/v1/attachments/{className}/{id}/{childClassName}/?fileName={fileName}
  • URL Parameters:
    • className - required - Cartegraph class name (for example, cgSignsClass)
    • id - required - Oid of the record
    • childClassName - required - Cartegraph class name (for example, cgSigns_cgAttachmentsClass)
    • fileName - required - Requested name for the file. If the filename is not unique in the final directory it will be appended by an underscore and a number to make the filename unique. (for example, PlanA.docx or PlanA_1.docx)
  • File:
    • A file is required to be uploaded with the request. The binary can be uploaded in multipart/form-data or as the entire body of the request
    • When uploading a file via multipart/form-data, the file's Content-Disposition header's name attribute (sometimes referred to as the form-data key in some REST clients) and filename attribute are not used for a special purpose by the API, but they may need to have valid values
    • Only one file can be uploaded at a time

Example Requests

Add the attachment PlanA.docx to the Request 1234 :

POST http://localhost/Cartegraph/api/v1/attachments/cgRequestsClass/1234/cgRequests_cgAttachmentsClass/?filename=PlanA.docx

Example Responses

One Request attachment created for the PlanA.docx:

{
    "Oid": 1495227176,
    "FileName": "PlanA.docx"
}

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains a JSON object containing the properties: `
      • Oid: Oid of the attachment record created
      • FileName: Final name of the file in the project home
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name/Oid in the URL
    • Invalid URI path. {uriPath} has more URI segments than is allowed.
      • The URL contains more than the valid number of URI segments for that given URI.
      • In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the URL specification in order to view URL examples with valid numbers of segments.
      • Example: For a POST, /cgSignsClass/651592699/cgSigns_cgAttachmentsClass/2131404296 -- There are more than three segments (in this example, /{className}/{id}/{className}/{id}).
    • {className} is not a valid class name
      • An invalid class name was entered in the URL
      • Example: /cgblahClass/AB1234/cgblah_cgAttachmentsClass -- cgBlahClass does not exist in the OMS database so it is invalid.
    • Invalid URI path. {className} is not child to {different className}
      • The URL contains a bad relationship in classes
      • Example: /cgSignsClass/730298513/cgRequests_cgAttachmentsClass -- Signs does not have a child recordset of Request attachments.
    • {className} is not an attachments recordset.
      • The class name specified is not for an attachments recordset
    • A parent oid is missing.
      • There is no parent oid in the URL
    • Unable to convert {id} to an oid
      • An invalid value was entered for an Oid in the URL
      • Example: /cgRequestsClass/AB1234/cgRequests_cgAttachmentsClass -- Oids are numbers and cannot contain letters.
    • Cannot specify the oid in the URL for a create.
      • The URL has on Oid at the end. This is not allowed for a create. It is OK to have Oid in the JSON but not at the end of the URL
    • Cannot find a {className} record with an oid of {id}.
      • The parent record could not be found
    • The file is empty or there was no file provided.
      • No file or no byes where found to upload.
    • Cannot upload more than 1 file at a time.
      • Only 1 file can be uploaded at a time
    • A file name is missing
      • The fileName paramater is missing or does not specify a value
    • The attachment has an invalid file type.
      • The attachment file type is not allowed. Refer to the web.config for the list of file types rejected by the server
  • 403 Forbidden
    • The System Administrator prevented your access to this feature. Ask the System Administrator for help with access.
      • Security Role assigned to the User Account does not have permissions to the Link/Upload Attachment command for the parent recordset or the Create action for the attachment recordset.
  • 500 Internal Server Error
    • An error occurred on the server while trying to create
      • Maximum request length exceeded.
        • The file is larger than the limit specified in the web server's Web.config

Delete

  • Purpose: Delete one attachment record and associated file.
  • HTTP Method: DELETE
  • URL:
    • https://yourserver.com/cartegraph/api/v1/attachments/{className}/{id}
  • URL Parameters:
    • className - required - Cartegraph class name (for example, cgSignsClass)
    • id - required - Oid of the record

Example Requests

Delete the file associated to the Sign Attachment record with Oid 435560664:

DELETE https://yourserver.com/cartegraph/api/v1/attachments/cgSigns_cgAttachmentsClass/435560664

Example Responses

Delete the file associated to the Sign Attachment record with Oid 435560664:

{
    "DeletedRecordCount": 1
}

Status Codes Returned and Common Error Messages

  • 200 OK
    • The message body contains a JSON object containing a DeletedRecordCount property that indicates the number of records deleted.
  • 400 Bad Request
    • Identifier cannot be empty. Please specify an identifier.
      • There is no class name/Oid in the URL
    • Invalid URI path. {uriPath} has more URI segments than is allowed.
      • The URL contains more than the valid number of URI segments for that given URI.
      • In this document under the applicable HTTP verb section (GET, POST, etc.), refer to the URL specification in order to view URL examples with valid numbers of segments.
      • Example: For a DELETE, cgSigns_cgAttachmentsClass/ -- There are less than two segments (in this example, /{className}/ where it should be: /{className}/{id}).
    • {className} is not a valid class name
      • An invalid class name was in the URL
      • Example: cgBlahClasss_cgAttachmentsClass/1234 -- cgBlahClasss_cgAttachmentsClass does not exist in the OMS database so it is invalid.
    • {className} is not an attachments recordset.
      • The class name specified is not for an attachments recordset
    • Oid is required
      • This message is given when an Oid is missing in the URL
    • Unable to convert {id} to an oid
      • An invalid value for an Oid was in the URL
      • Example: /cgSignsClass/AB1234 -- Oids are numbers and cannot contain letters.
  • 403 Forbidden
    • The System Administrator prevented your access to this feature. Ask the System Administrator for help with access. Security Role assigned to the User Account does not have permissions to the Delete action for {className}.
  • 500 Internal Server Error
    • An error occurred on the server while trying to delete
      • Example: "Record cannot be found. Ask your System Administrator for help. Cannot find cgRequests_cgAttachmentsClass record with OID = 123"