(the source of primary image of this article is from https://bimnature.wordpress.com/2018/01/29/bim-360-docs-new-rfi-workflows/)
An RFI (Request for Information) is a formal question asked by one project member of another, such as clarification of design intent from the architect. You can manage the RFI workflow by assigning members to the RFI, transitioning the RFI to different states, and adding comments and attachments.
RFI set move between contractors, managers, and reviewers in one workflow. Check this product help for more info on the standard workflow.
API documents provides API Endpoint Reference, Tutorials, API Basic(features, terminologies, limitations etc.). This blog is going to highlight some notes with RFI APIs.
API Basic features
• get RFI collection and data of single RFI
• get RFI comments and attachments
• get RFI associated document and pushpin data
• get permitted action of next transition.
• modify general data
• transfer RFI to next role and update status
• create new RFI without associating document, or pushpin RFI with one document
• create new comments
• associate existing files as attachment of RFI
• delete attachment
Special Notes
- RFI supports 3Legged token only
- A user should be project member or project admin
- A user should be assigned with a role in the workflow. Project admins are automatically assigned the creator workflow role. GET users/me tells which role one use have and which type.
- API does not currently support adding local file as attachment of RFIs.
- API tells the user id of permitted role. By the other GET Project Users, you can get the name of the user.
Workflow Role
To check the workflow roles assigned to the project members, see GET users/me. e.g. In a test project, the roles are defined in UI:
If using 3Legged token of Xiaodong Liang, the response shows he is projectSC (Creator).
{
"user": {
"id": "XXXXXX",
"name": "Xiaodong Liang",
"role": "project_admin"
},
"permittedActions": {
"createRfi": {
"permittedStatuses": [
{
"status": "draft",
"requiredAttributes": [
{
"name": "title"
}
]
},
{
"status": "submitted",
"requiredAttributes": [
{
"name": "title"
},
{
"name": "assignedTo",
"values": [
{
"value": "YYYYY",
"type": "user"
},
{
"value": "ZZZZZ",
"type": "user"
}
]
}
]
},
{
"status": "open",
"requiredAttributes": [
{
"name": "title"
},
{
"name": "assignedTo",
"values": [
{
"value": "YYYYY",
"type": "user"
},
{
"value": "MMMMM",
"type": "user"
}
]
}
]
}
]
}
},
"workflow": {
"roles": [
"projectSC"
],
"type": "US"
}
}If using 3Legged token of DevTechChina, the response shows the member has role "projectGC" and "projectArch" (Manager and Reviewer)
{
"user": {
"id": "BVE5MB3YCEMF",
"name": "Devtech China",
"role": "project_user"
},
"permittedActions": {
"createRfi": {
"permittedStatuses": [
{
"status": "draft",
"requiredAttributes": [
{
"name": "title"
}
]
},
{
"status": "open",
"requiredAttributes": [
{
"name": "title"
},
{
"name": "assignedTo",
"values": [
{
"value": "BVE5MB3YCEMF",
"type": "user"
},
{
"value": "L9EJL4RU3NSR",
"type": "user"
}
]
}
]
}
]
}
},
"workflow": {
"roles": [
"projectGC",
"projectArch"
],
"type": "US"
}
}
The below is a terminology of UI and API:
RFI Transitions
RFI looks like Issue, while the key difference is the RFI follows the workflow transition. e.g. role of creator can only transfer RFI to the role of manager to answer, manager can only send to the reviewer to close/open etc. Since RFI API tells permitted action of next transition, we can follow the actions to assign to the next valid role user. e.g. assume one RFI is just created by creator as a draft, its permitted actions are:
"permittedStatuses": [
{
"status": "submitted",
"requiredAttributes": [
{
"name": "assignedTo",
"values": [
{
"value": "YYYYYY",
"type": "user"
},
{
"value": "ZZZZZZZ",
"type": "user"
}
]
}
]
},
{
"status": "open",
"requiredAttributes": [
{
"name": "assignedTo",
"values": [
{
"value": "ZZZZZZ",
"type": "user"
},
{
"value": "MMMMM",
"type": "user"
}
]
}
]
},
{
"status": "void",
"requiredAttributes": []
}
]It indicates, it can be transferred to the next status are: Submitted for Managers, or Open for Reviewers . So, call PATCH RFI, with the body below, it will succeed with the transition to Manager. IF it is not a valid user, or un-permitted actions, it will fail.
{
"status": "submitted",
"assignedTo": "YYYYY"
}Note: if the permitted status does not require assignTo (such as closed) , the back-end of RFI logic will take care of the assignedTo. It cannot be changed by API now. So only set status to closed when you want to close an RFI.
RFI Transitions tutorial and Postman scripts demo a complete sample workflow.
Pushpin RFI
pushpin RFI is a kind of type that associates with the specific location (and object) of the model in visual. The general step is: the end user picks a location of the model in Forge Viewer, the code will get the view state, position, object id and document urn, finally create the RFI with these data. Right now, without Viewer, it is not possible to know the position of an object and view state, so to implement a workflow of Pushpin RFI, it assumes the app will depend on Forge Viewer.
Forge Viewer also provides an extension of Pushpin, which introduces the similar experience of BIM 360 product. Actually this extension supports Issue, RFI, Submittal. The workflow is similar.
To render the pushpin RFI, firstly, use API to get the data of RFI, and inject to Pushpin extension, it will show up the pushpin icon and the basic information of the RFI To create a pushpin RFI, firstly, the function of this extension can launch a process to ask the end user to pick a location in the viewer, and it tells view state, object id, position etc. By these data, call POST RFI endpoint to create the RFI.
The tutorial in Forge help re-used the document of Pushpin Issue. While this document contents is only compatible with old version of Viewer (< v7.0) and previous usage of extension. I would recommend with the migrated code project . though it demos Issue pushpin only, as mentioned above, it is similar with RFI. The only difference are:
- Pushpin type
- GET/POST endpoints (Issue API for Issue, RFI API for RFI)
- With RFI, some data of Issue API (such as issue type, sub type) are not required.
Postman Scripts
This scripts includes API reference, which demos basic usage of each endpoint. You may try different query param, or payload body to verify the API features.
This scripts also includes some tutorial demos:
- Workflow : Draft>>Submitted->Open->Answered>>Closed
- Create RFI, add comment and get comments
- Create RFI, add exiting document as attachment, and delete attachment
More tutorials will be available in the future. The Postman scripts can be found at forge-bim360.rfi.api-postman.collection
For RFI V1 Users
If you have played RFI version 1, the experience with version 2 is very similar. Some differences:
- GET users/me tells the permitted status of RFI which the user can perform, including the next action and possible assignees. The term ‘transition’ of v1 is retired. No specific term now, but the workflow is enclosed under permittedActions >>permittedStatuses>>requiredAttributes.
- GET user/me only tells the permission of RFI of the user. While in v1, it also tells permission of issue, checklist etc. which is complex.
- GET: RFI collection returns much less data than v1. More succinct. Some detail data are removed, yet available with GET RFI/:id.
- Content Type is now application/json. In v1, it is application/vnd.api+json
- In version 2, it supports to create RFI with draft, open or submitted.
A couple of more features are scheduled in the roadmap, e.g. Workflow definition API (e.g. switch workflow type, assign role to user); Support local file as attachment for the RFI etc. And we will also provide a sample on batch exporting or editing RFI.
We welcome any feedbacks with this RFI API. Should you have any comments, please free feel to submit the question at forge.help@autodesk.com