Box

the box connector allows for streamlined automation of content management functions, enabling secure file sharing and collaboration within enterprise workflows box is a cloud content management and file sharing service for businesses the box connector for swimlane turbine enables automated interactions with box, allowing users to manage files, folders, collaborations, and events within their box environment by integrating with box, swimlane turbine users can streamline content workflows, enhance collaboration security, and maintain a seamless data exchange across their security ecosystem this connector empowers users to perform a variety of actions such as uploading files, managing upload sessions, and retrieving file or folder details, all within the swimlane platform the box api to interact with various aspects of the box content collaboration product this connector focuses on apis related to files, collaborations, users, events, folders, shared links, search, workflow, groups, and upload prerequisites to utilize the box connector within swimlane turbine, ensure you have the following prerequisites oauth 2 0 authentication with the following parameters url endpoint for box api services access token token used to authenticate api requests custom authentication with the following parameters url endpoint for box api services client id unique identifier for the application using the box api client secret secret key associated with the client id for authentication grant type type of oauth grant requested (e g , client credentials) note link to authentication https //developer box com/reference/post oauth2 token/link to authentication using oauth2 0 https //developer box com/guides/authentication/oauth2/ the swimlane team will provide a python script and instructions on how to use the script to generate the access token using oauth2 0 capabilities this connector provides the following capabilities commit upload session create upload session for existing file create upload session get collaborations get events get file from shared link get file get folder for shared link get group get list items in folder get list parts get metadata query get upload session get user get workflows and so on note interact with files api reference https //developer box com/reference/get files id/ manage collaborations api reference https //developer box com/reference/get collaborations id/ manage users api reference https //developer box com/reference/get users id/ handle events api reference https //developer box com/reference/get events/ manage folders api reference https //developer box com/reference/get folders id items/ handle shared links (folders) api reference https //developer box com/reference/get shared items folders/ handle shared links (files) api reference https //developer box com/reference/get shared items/ execute search api reference https //developer box com/reference/get metadata query indices/ handle workflow api reference https //developer box com/reference/get workflows/ manage groups api reference https //developer box com/reference/get groups id/ handle uploads api reference https //developer box com/reference/post files content/ handle chunked uploads api reference https //developer box com/reference/get files upload sessions id/ configurations box authentication using oauth2 0 configuration parameters parameter description type required url a url to the target host string required access token the access token string required verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional box authentication configuration parameters parameter description type required url a url to the target host string required client id the client id string required client secret the client secret string required actor token the actor token string optional actor token type the actor token type string optional assertion the assertion string optional box shared link the box shared link string optional box subject id the box subject id string optional box subject type the box subject type string optional code the code string optional grant type the grant type string required refresh token the refresh token string optional resource the resource string optional scope the scope string optional subject token the subject token string optional subject token type the subject token type string optional verify ssl verify ssl certificate boolean optional http proxy a proxy to route requests through string optional actions commit upload session closes an active upload session using the 'upload session id' and creates a file from the uploaded parts in box endpoint url /files/upload sessions/{{upload session id}}/commit method post input argument name type required description upload session id string required unique identifier parts array required parameter for commit upload session part id string required unique identifier offset number required parameter for commit upload session size number required parameter for commit upload session sha1 string required parameter for commit upload session headers object required http headers for the request digest string required parameter for commit upload session if match string optional parameter for commit upload session if none match string optional parameter for commit upload session output parameter type description status code number http status code of the response reason string response reason phrase entries array output field entries id string unique identifier etag string output field etag type string type of the resource sequence id string unique identifier name string name of the resource sha1 string output field sha1 file version object output field file version id string unique identifier type string type of the resource sha1 string output field sha1 description string output field description size number output field size path collection object output field path collection total count number count value entries array output field entries id string unique identifier etag string output field etag type string type of the resource sequence id string unique identifier name string name of the resource example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "entries" \[] } } ] create upload session initiates an upload session in box for a new file, requiring the file's name, size, and target folder id endpoint url /files/upload sessions method post input argument name type required description file name string required name of the resource file size number required parameter for create upload session folder id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier type string type of the resource num parts processed number output field num parts processed part size number output field part size session endpoints object output field session endpoints abort string output field abort commit string output field commit list parts string output field list parts log event string output field log event status string status value upload part string output field upload part session expires at string output field session expires at total parts number output field total parts example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "id" "f971964745a5cd0c001bbe4e58196bfd", "type" "upload session", "num parts processed" 455, "part size" 1024, "session endpoints" {}, "session expires at" "2012 12 12t10 53 43 08 00", "total parts" 1000 } } ] create upload session for existing file initiates an upload session for a specified existing file on box, requiring the file's id and size endpoint url /files/{{file id}}/upload sessions method post input argument name type required description file id string required unique identifier file name string optional name of the resource file size number required parameter for create upload session for existing file output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier type string type of the resource num parts processed number output field num parts processed part size number output field part size session endpoints object output field session endpoints abort string output field abort commit string output field commit list parts string output field list parts log event string output field log event status string status value upload part string output field upload part session expires at string output field session expires at total parts number output field total parts example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "id" "f971964745a5cd0c001bbe4e58196bfd", "type" "upload session", "num parts processed" 455, "part size" 1024, "session endpoints" {}, "session expires at" "2012 12 12t10 53 43 08 00", "total parts" 1000 } } ] get collaborations retrieves details for a specific collaboration in box using the provided collaboration id endpoint url /collaborations/{{collaboration id}} method get input argument name type required description collaboration id string required unique identifier fields array optional parameter for get collaborations id string optional unique identifier type string optional type of the resource name string optional name of the resource output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier type string type of the resource acceptance requirements status object status value strong password requirement object output field strong password requirement enterprise has strong password required for external users boolean output field enterprise has strong password required for external users user has strong password boolean output field user has strong password terms of service requirement object output field terms of service requirement is accepted boolean output field is accepted terms of service object output field terms of service id string unique identifier type string type of the resource two factor authentication requirement object output field two factor authentication requirement enterprise has two factor auth enabled boolean output field enterprise has two factor auth enabled user has two factor authentication enabled boolean output field user has two factor authentication enabled accessible by object output field accessible by id string unique identifier type string type of the resource login string output field login name string name of the resource acknowledged at string output field acknowledged at created at string output field created at created by array output field created by id number unique identifier example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "id" "12345678", "type" "collaboration", "acceptance requirements status" {}, "accessible by" {}, "acknowledged at" "2012 12 12t10 55 20 08 00", "created at" "2012 12 12t10 53 43 08 00", "created by" \[], "expires at" "2012 12 26t10 53 43 08 00", "invite email" "john\@example com", "is access only" true, "item" {}, "modified at" "2012 12 12t10 53 43 08 00", "role" "editor", "status" "accepted" } } ] get events retrieves up to a year of past events for a specified user or the entire enterprise on box endpoint url /events method get input argument name type required description created after string optional parameter for get events created before string optional parameter for get events event type string optional type of the resource limit number optional parameter for get events stream position string optional parameter for get events stream type string optional type of the resource output parameter type description status code number http status code of the response reason string response reason phrase chunk size number output field chunk size entries array output field entries type string type of the resource created at string output field created at recorded at string output field recorded at event id string unique identifier created by object output field created by id string unique identifier type string type of the resource name string name of the resource login string output field login event type string type of the resource session id string unique identifier source object output field source id string unique identifier type string type of the resource name string name of the resource login string output field login created at string output field created at modified at string output field modified at language string output field language timezone string output field timezone space amount number output field space amount example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "chunk size" 2, "entries" \[], "next stream position" "1152922976252290886" } } ] get file retrieves the details of a specific file from box using the provided file id as a path parameter endpoint url /files/{{file id}} method get input argument name type required description file id string required unique identifier fields array optional parameter for get file id string optional unique identifier type string optional type of the resource name string optional name of the resource headers object optional http headers for the request boxapi string optional parameter for get file if none match string optional parameter for get file x rep hints string optional parameter for get file output parameter type description status code number http status code of the response reason string response reason phrase has collaborations boolean output field has collaborations is accessible via shared link boolean output field is accessible via shared link is externally owned boolean output field is externally owned is package boolean output field is package item status string status value lock object output field lock id string unique identifier type string type of the resource app type string type of the resource created at string output field created at created by object output field created by id string unique identifier type string type of the resource login string output field login name string name of the resource expired at string output field expired at is download prevented boolean output field is download prevented id string unique identifier type string type of the resource allowed invitee roles array output field allowed invitee roles token type string type of the resource url string url endpoint for the request example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "id" "12345", "type" "file", "allowed invitee roles" \[], "token type" "bearer", "url" "https //cloud app box com/preview/expiring embed/ " }, "has collaborations" true, "is accessible via shared link" true, "is externally owned" true, "is package" true, "item status" "active", "lock" { "id" "11446498", "type" "lock", "app type" "office wopiplus", "created at" "2012 12 12t10 53 43 08 00", "created by" {}, "expired at" "2012 12 12t10 53 43 08 00", "is download prevented" true } } ] get file from shared link retrieves a file from box using a shared link, requiring specific headers for authorization endpoint url /shared items method get input argument name type required description fields array optional parameter for get file from shared link id string optional unique identifier type string optional type of the resource name string optional name of the resource headers object required http headers for the request boxapi string required parameter for get file from shared link if none match string optional parameter for get file from shared link output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier type string type of the resource allowed invitee roles array output field allowed invitee roles purged at string output field purged at representations object output field representations entries array output field entries content object response content url template string url endpoint for the request info object output field info url string url endpoint for the request properties object output field properties dimensions string output field dimensions paged boolean output field paged thumb boolean output field thumb representation string output field representation status object status value state string output field state example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "id" "12345", "type" "file", "allowed invitee roles" \[], "purged at" "2012 12 12t10 53 43 08 00", "representations" {} } } ] get folder for shared link retrieve the folder associated with a provided shared link in box, requiring specific headers for authentication endpoint url /shared items method get input argument name type required description fields array optional parameter for get folder for shared link id string optional unique identifier type string optional type of the resource name string optional name of the resource headers object required http headers for the request boxapi string required parameter for get folder for shared link if none match string optional parameter for get folder for shared link output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier type string type of the resource allowed invitee roles array output field allowed invitee roles allowed shared link access levels array output field allowed shared link access levels name string name of the resource owned by object output field owned by id string unique identifier type string type of the resource login string output field login name string name of the resource example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "id" "12345", "type" "folder", "allowed invitee roles" \[], "allowed shared link access levels" \[], "name" "contracts", "owned by" {} } } ] get group retrieves details for a specified group in box, accessible by group members or admin level users endpoint url /groups/{{group id}} method get input argument name type required description group id string required unique identifier fields array optional parameter for get group id string optional unique identifier type string optional type of the resource name string optional name of the resource output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier type string type of the resource created at string output field created at description string output field description external sync identifier string unique identifier group type string type of the resource invitability level string output field invitability level member viewability level string output field member viewability level modified at string output field modified at name string name of the resource permissions object output field permissions can invite as collaborator boolean output field can invite as collaborator provenance string output field provenance example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "id" "11446498", "type" "group", "created at" "2012 12 12t10 53 43 08 00", "description" "support group as imported from active directory", "external sync identifier" "ad 123456", "group type" "managed group", "invitability level" "admins only", "member viewability level" "admins only", "modified at" "2012 12 12t10 53 43 08 00", "name" "support", "permissions" {}, "provenance" "active directory" } } ] get list items in folder retrieves a list of items within a specified folder on box, including files, folders, and web links, identified by the folder id endpoint url /folders/{{folder id}}/items method get input argument name type required description folder id string required unique identifier direction string optional parameter for get list items in folder limit number optional parameter for get list items in folder marker string optional parameter for get list items in folder offset number optional parameter for get list items in folder sort string optional parameter for get list items in folder usemarker boolean optional parameter for get list items in folder fields array optional parameter for get list items in folder id string optional unique identifier type string optional type of the resource name string optional name of the resource headers object optional http headers for the request boxapi string optional parameter for get list items in folder output parameter type description status code number http status code of the response reason string response reason phrase limit number output field limit offset number output field offset order array output field order by string output field by direction string output field direction total count number count value example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "limit" 1000, "offset" 2000, "order" \[], "total count" 5000 } } ] get list parts retrieve a list of uploaded file chunks for a given upload session in box using the specified upload session id endpoint url /files/upload sessions/{{upload session id}}/parts method get input argument name type required description upload session id string required unique identifier limit number optional parameter for get list parts offset number optional parameter for get list parts output parameter type description status code number http status code of the response reason string response reason phrase entries array output field entries part id string unique identifier offset number output field offset size number output field size sha1 string output field sha1 limit number output field limit offset number output field offset order array output field order by string output field by direction string output field direction total count number count value example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "entries" \[], "limit" 1000, "offset" 2000, "order" \[], "total count" 5000 } } ] get metadata query retrieves metadata query indices in box for a specified scope and template key, requiring 'scope' and 'template key' parameters endpoint url /metadata query indices method get input argument name type required description scope string required parameter for get metadata query template key string required parameter for get metadata query output parameter type description status code number http status code of the response reason string response reason phrase entries array output field entries id string unique identifier type string type of the resource status string status value fields array output field fields key string output field key sort direction string output field sort direction limit number output field limit next marker string output field next marker example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "entries" \[], "limit" 100, "next marker" "0! m7487opvfbtnbv xsqju50gqflbffu5narmwd7ck61gh qo40m1s2xn5zwzpbzejaqs1sojjiqoo5 " } } ] get upload session retrieve details of a specific upload session in box using the provided upload session id endpoint url /files/upload sessions/{{upload session id}} method get input argument name type required description upload session id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier type string type of the resource num parts processed number output field num parts processed part size number output field part size session endpoints object output field session endpoints abort string output field abort commit string output field commit list parts string output field list parts log event string output field log event status string status value upload part string output field upload part session expires at string output field session expires at total parts number output field total parts example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "id" "f971964745a5cd0c001bbe4e58196bfd", "type" "upload session", "num parts processed" 455, "part size" 1024, "session endpoints" {}, "session expires at" "2012 12 12t10 53 43 08 00", "total parts" 1000 } } ] get user retrieves detailed information about a specified user in the box enterprise environment using their user id endpoint url /users/{{user id}} method get input argument name type required description user id string required unique identifier fields array optional parameter for get user id string optional unique identifier type string optional type of the resource name string optional name of the resource output parameter type description status code number http status code of the response reason string response reason phrase id string unique identifier type string type of the resource address string output field address avatar url string url endpoint for the request can see managed users boolean output field can see managed users created at string output field created at enterprise object output field enterprise id string unique identifier type string type of the resource name string name of the resource external app user id string unique identifier hostname string name of the resource is exempt from device limits boolean output field is exempt from device limits is exempt from login verification boolean output field is exempt from login verification is external collab restricted boolean output field is external collab restricted is platform access only boolean output field is platform access only is sync enabled boolean output field is sync enabled job title string output field job title language string output field language login string output field login max upload size number output field max upload size modified at string output field modified at my tags array output field my tags example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "id" "11446498", "type" "user", "address" "900 jefferson ave, redwood city, ca 94063", "avatar url" "https //www box com/api/avatar/large/181216415", "can see managed users" true, "created at" "2012 12 12t10 53 43 08 00", "enterprise" {}, "external app user id" "my user 1234", "hostname" "https //example app box com/", "is exempt from device limits" true, "is exempt from login verification" true, "is external collab restricted" true, "is platform access only" true, "is sync enabled" true, "job title" "ceo" } } ] get workflows retrieves a list of manual start workflows associated with a specified folder id in box endpoint url /workflows method get input argument name type required description folder id string required unique identifier limit number optional parameter for get workflows marker string optional parameter for get workflows trigger type string optional type of the resource output parameter type description status code number http status code of the response reason string response reason phrase entries array output field entries id string unique identifier type string type of the resource name string name of the resource description string output field description is enabled boolean output field is enabled flows array output field flows id string unique identifier type string type of the resource trigger object output field trigger type string type of the resource trigger type string type of the resource scope array output field scope type string type of the resource ref string output field ref object object output field object outcomes array output field outcomes id string unique identifier type string type of the resource name string name of the resource action type string type of the resource if rejected array output field if rejected id string unique identifier example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "entries" \[], "limit" 1000, "next marker" "jv9irgzmieibasejog9ydcrngd2ymozibjsxbjmjis3kiovii", "prev marker" "jv9irgzmieibasejog9ydcrngd2ymozibjsxbjmjis3kiovih" } } ] remove upload session aborts an ongoing box upload session and discards all associated data using the specified upload session id endpoint url /files/upload sessions/{{upload session id}} method delete input argument name type required description upload session id string required unique identifier output parameter type description status code number http status code of the response reason string response reason phrase example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" {} } ] upload file uploads a small file to box using provided data body, form data, and headers endpoint url /files/content method post input argument name type required description fields array optional parameter for upload file id string optional unique identifier type string optional type of the resource name string optional name of the resource data body object required response data attributes object required parameter for upload file content created at string required response content content modified at string required response content name string required name of the resource parent object optional parameter for upload file id string required unique identifier form data object required response data files array required parameter for upload file file name string required name of the resource file string required parameter for upload file headers object required http headers for the request content md5 string optional response content output parameter type description status code number http status code of the response reason string response reason phrase entries array output field entries parent object output field parent id string unique identifier etag string output field etag type string type of the resource sequence id string unique identifier name string name of the resource tags array output field tags watermark info object output field watermark info is watermarked boolean output field is watermarked expires at string output field expires at representations object output field representations entries array output field entries content object response content url template string url endpoint for the request info object output field info url string url endpoint for the request properties object output field properties dimensions string output field dimensions paged boolean output field paged thumb boolean output field thumb representation string output field representation status object status value example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "entries" \[], "total count" 1 } } ] upload part of file updates a specific chunk of a file during an upload session in box, requiring the upload session id endpoint url /files/upload sessions/{{upload session id}} method put input argument name type required description upload session id string required unique identifier headers object required http headers for the request content range string required response content digest string required parameter for upload part of file output parameter type description status code number http status code of the response reason string response reason phrase part object output field part offset number output field offset part id string unique identifier sha1 string output field sha1 size number output field size example \[ { "status code" 200, "reason" "ok", "response headers" {}, "json body" { "part" {} } } ]