A Request for Information (RFI) is a formal process used to obtain clarification or additional information from architects, engineers, clients, or other stakeholders involved in a construction project. If you worked on Autodesk Build RFI integration, you will know the history that ACC RFI v2 API was consolidated with BIM360 RFI API from year 2022. Since then, the v2 API has been deprecated. However, not all features or entity data of ACC RFI are supported with BIM360 API.
Now we are exciting to announce ACC RFI v3 API is released in general availability. It provides plentiful functionality support. The endpoints are available with the base url: /construction/rfis/v3/projects/:projectId. The Field Guide describes the overview of this release. To migrate from BIM360 API, please check the other blog.
API List
- RFI Types
- GET /rfi-types: get available RFI types defined in this project
- Workflow
- GET /workflow: get current workflow with the active RFI type.
- RFIs:
- GET /users/me: get permission information and roles of logged user
- POST: /search:rfis: get RFI collection and search by text or filter by attributes
- GET /rfis/:id: get single RFI data
- POST /rfis: create a new RFI
- PATCH /rfis/:id: update a RFI
- Response
- POST /rfis/:rfiId/responses: create response to the RFI with/without attachments
- PATCH /rfis/:rfiId/responses/:responseId: upadte a response with/without attachment
- Comments
- GET /rfis/:rfiId/comments: get comments list of one RFI
- POST /rfis/:rfiId/comments: create one comment to RFI
- Attachments
- GET /rfis/:rfiId/attachments: get all attachments associated with one RFI
- Custom Attributes
- GET /attributes: get RFI custom attributes definitions of this project
- POST /attributes: create RFI custom attributes definitions
- PATCH /attributes/:attributeId: update a custom attributes definition
- Custom-Identifier
- GET /rfis/custom-identifier: get next available custom identifier for RFIs
Highlighted Notes
Get All RFIs
In this release, there is no specific endpoint of GET RFIs collection as usual. The endpoint POST /search:rfis plays the role to search RFIs, and also return all RFIs when the payload is empty json {} or filter is empty.
RFI Permission
The roles defines the basic permission of the user in the transition workflow. GET /workflow reflects what are configured in UI>>Permissions. The GET /users/me will tell which roles the logged user (for authorizing API access) have in the workflow, including what permitted actions and assignees that this user can perform when creating a new RFI.
The terminologies in API v.s. UI.
The RFI Type can define the default managers, reviewers and watchers. The setting will be reflected in GET: /rfi-types. Note: the available managers or reviewers for default come from the Permissions above, while the default watchers can be anybody in this project.
For details on permission management, please check API help documents.
Transition
Transition RFI follows the transition defined in the workflow. When one user (in API) transits (updates) the RFI, he/she will follow the permission with this RFI. So, from API perspective, the app must firstly check permittedActions, permittedAttributes, this user can perform for a particular RFI. Otherwise, the API will refuse to take action and return error. In addition, requiredAttributes indicate which attributes that are needed with the the corresponding actions. e.g. the data of one RFI below means: the logged user can update the RFI from current status to draft to open or void, with one of the required attributes assignedTo (to AAAA, BBBB or CCC)
{
"id": "17623819-3b9e-4a22-b421-73c446c1ba65",
"title": "Test Response",
"status": "draft",
"workflowType": "US",
"permittedActions": {
"updateRfi": {
"permittedAttributes": [
{
"name": "assignedTo",
"values": [ { "value": "CCCC","type": "user"},
{ "value": "BBBB","type": "user" },
{ "value": "AAAA", "type": "user"}
]
},
{
"name": "status",
"values": [ { "value": "open"},
{ "value": "void" }
]
}
<other attributes, trimmed>
],
"permittedStatuses": {
"wfUS": [
{
"status": "open",
"requiredAttributes": [
{
"name": "assignedTo",
"values": [
{ "value": "CCCC","type": "user"},
{ "value": "BBBB","type": "user" },
{ "value": "AAAA", "type": "user"}
]
}
],
"permittedAttributes": [
<trimmed other attributes>
],
"maxAssignees": 10
},
{
"status": "void",
<trimmed other attributes>
}
],
"wfEU": [
{
<trimmed other attributes>
}
]
}
},
"createComment": true,
"createResponse": false,
"remainingReviewers": [],
"createResponseOnBehalf": false
}
} Response
To submit an individual response, the app will call POST /rfis/:rfiId/responses. Similar to transition, the app will firstly check if this user can create response by the flag createResponse or can create response for other permitted users by the flag createResponseOnBehalf. e.g. the payload below means the current user will create a response on behalf of user BBBB.
{
"status": "answered",
"text": "test the response on behalf" ,
"onBehalf": "BBBB"
} To create an official response for a RFI, the app will call PATCH /rfis/:id . The user must have manager permission and the RFI status is answered. The payload will be looked like:
{
"status": "closed",
"officialResponse": "This is my official response text",
"officialResponseStatus": "answered"
} The manager or admin can skip response of all reviewers. However the RFI must have at least one response before this action is allowed. After first response is available, the body with PATCH /rfis/:id could be just {status: "answered"}.
remainingReviewers in the data of RFI indicates who has not responded in the list of Ball in Court.
Attachments
The binary file of Attachment is managed by Data Management API. The steps to download and upload are similar to the general file in ACC Docs. The difference is the attachment files locates in the hidden of the specific RFI. Each RFI has one virtual folder. You can fetch its urn id (virtualFolderUrn) from the RFI data . After that, upload the file to the folder storage. Finally call POST /rfis/:rfiId/responses to create individual response with attachment, e.g.
{
"status": "answered",
"test": "This is my response text",
"onBehalf": "AAAA",
"attachments": [
{
"attachmentType": "rfiResponse"
"displayName": "My attachments.pdf"
"fileName": "a2615894-f133-4334-a235-5f8d558a2467.pdf"
"storageUrn": "urn:adsk.objects:os.object:wip.dm.prod/a2615894-f133-4334-a235-5f8d558a2467.pdf"
}
]
} Or, call PATCH /rfis/:id when you want to create official response with attachment data in the payload, to associate attachment to the official response. e.g.
{
"status": "closed",
"officialResponse": "This is my official response text",
"officialResponseStatus": "answered",
"attachments": [
{
"attachmentType": "rfiOfficialResponse"
"displayName": "My attachments.pdf"
"fileName": "a2615894-f133-4334-a235-5f8d558a2467.pdf"
"storageUrn": "urn:adsk.objects:os.object:wip.dm.prod/a2615894-f133-4334-a235-5f8d558a2467.pdf"
}
]
} It is recommended to reuse the object key of the storage as fileName. Currently, only individual response or official response can attach attachments. This tutorial describes detail steps on how to create response with attachment.
Note: when an RFI is being created, the internal mechanism runs an asynchronous job to setup virtual folder. It may take a little moment to complete it. Please call GET /rfis/:id to verify this attribute is available before moving to the next step of uploading attachments.
Custom Attributes
There are 4 types with custom attributes definitions: text, numeric, single choices, multiple choices. The type of definition data only manages text and numeric, while multipleChoice indicates it is single or multiple choices. multipleChoice is more prioritized. If you call POST /attributes with the payload below, it will create a single choice type, instead of text. So be careful not to work with the two attributes for your purpose. Similarly, when GET: /attributes, please check firstly if multipleChoice attribute is available.
{
"name": "my test attributes definition",
"type": "text",
"description": "my purpose is to create a text",
"status": "active",
"multipleChoice": false,
"possibleValues": [
{
"id": "<UUID>",
"name": "some value"
}
]
} To set or update custom attribute value of the RFI, POST: /rfis or PATCH /rfis/:id with customAttributes collection. Inside collection specify the attribute definition id and value(text or numeric), or option id single or multiple choices).
{
"customAttributes": [
{
"id": "9a4e8b75-34ae-412c-a700-8aee4864effb",
"values": [
"text value (also in values array)"
]
},
{
"id": "92ba88ea-99cc-495c-b42a-d96ab65ea4fd", //e.g. multiple choices
"values": [
"a6379765-8622-4208-946b-17f3b75db49d",
"6a5c183b-867a-4edb-9971-fc09a782991b"
]
}
]
}Related Materials
- Field Guide
- Tutorials
- API Reference
- Postman Collection