Orchardcollaboration Customization, Part 1
In these series of posts, I will try to illustrate how you can customize Orchardcollaboration to fit your requirements. In this post, I show you how to customize the tickets by adding new fields to them. I will also show you how you can filter tickets based on the new field.
rchard is a free, open source, community-focused Content Management System built on the ASP.NET MVC platform. Orchard Collaboration is a free, open source ticketing system, project management and collaboration framework build on top of the Orchard CMS. It natively integrates with Orchard CMS and extends its features by allowing its users to collaboratively work on the content or by simplifying communication with the customers. Features of Orchardcollaboration includes Project management, tickets, wikis, milestones, cardwall, planner, discussions, activity stream per project to name but a few. If you are not familiar with the OrchardCollaboration, I explained how to install it here . You can find more documentation about it here.
When it comes to the ticketing systems, each organization has its own requirements and priorities. It means in many scenarios, they need to customize the collaboration software they are using. One of the common expectation is being able to add custom fields to the tickets. In this post, I show you how you can add new fields to Orchardcollaboration tickets, and later how to filter the tickets based on the new field.
Add a new Field to the Tickets
Orchard offers great deal of flexibility regarding extending the content types. By default, it is equipped with some predefined content types such as Pages, Blogs, etc. Orchardcollaboration extends it by adding special Content Types related to the Ticketing system such as Ticket Type, Business-Unit Type, Project Type, etc. Admin users can also define new Content Types, or customize the existing content types. Each Content-Type contains several ContentParts. ContentParts can be extended by adding Content-Fields to them. Orchard comes with a few built-in Content-Field types such as text, date or enumeration, but it is possible to build your own field types that can then be used to build new content types. If you are a developer and you want to create new Field Type, You can take a look at Orchard documentation here in order to find out how you can do that. Instances of content types in Orchard are called ContentItems. Generally speaking, the building blocks of the contents in Orchard are ContentItems.
Tickets in OrchardCollaboration are ContentItems too. The main ContentParts of the tickets are as follows:
Let's take a look at those ContentParts in action by navigating to one of the projects and clicking on add a new Ticket link as illustrated in the following figures.
As can be seen, the ticket has some default, hard-coded fields. Such fields comes from the ContentParts of the ticket. For example, Title, Description, Status, Type and Service are belong to TicketPart. Project and Milestone fields are related to the AttachToProject and AttachToMilestonePart respectively. Assigned User and Assigned Group fields come from ContentItemPermissionPart. What you see here is the frontend of the Orchard. In order to add a new field to tickets, we must switch to the backend of Orchard and change the definition of the TicketPart. In the next steps, I will add a custom field called Component to the tickets, which contains some predefined values.
In order to do so
1) After logging into the system as Administrator, navigate to the Admin dashboard.
2) Then click on Content Definition.
3) Select the “Content Parts” tab.
4) Scroll down to see Ticket Part and click on it.
5) Here, you can see the definition of the Ticket Part.
6) Click on the Add button to add a new field.
7) In the new window, change the name of the field to “Component”.
8) Select Enumeration Field type and click on Save button.
Now the new field is added to the TicketPart. Next step is configuring it in the Ticket Content Type. In order to do so,
1) In Orchard dashboard, click on “Content Definition” link.
2) In the Content Types page, scroll down to see Ticket Type, then click on it.
3) Expand the TicketPart. In the Options textarea, you can define values for the new field. Add some values here and then in the bottom of the page click on Save method.
We successfully added a new field to the ticket. Now, if you try to create a new ticket, you can see the new field in the properties section.
Filtering based on new the Field
In many use-cases, it is demanded to be able to filter the tickets based on the new fields too. A simple workaround is using Orchard Queries and Projections. In simple words, Orchard Queries are responsible for fetching data, and Orchard Projections are responsible for displaying data. What we need here is a new Orchard Query that filters the tickets based on the new field, and a Projection that displays the data fetched by the Query.
Creating a new Query in Orchard is pretty simple.
1) In the Orchard dashboard, click on the Queries link.
2) Here you can see the list of the Queries in the system. There are some Queries started with the “System_” prefix. These Queries are generated by OrchardCollaboration and they have been used by the system itself. Keep in mind that changing them affects the functionality of the Orchardcollaboration.
3) Click on the “Add a new Query” button.
4) In the opened page, provide a name for the new Query and then click on the Save button.
5) You will be navigated to the list of Queries again. This time you can see the new generated Query in the list. Click on its Edit link. (If there are more than ten Queries, the new Query will be in the second page).
6) Each Query consists of three sections. Filters, Sort Criteria and Layouts. In Filters section, you can select the necessary filters for your Query. In Sort Criteria, you can select a Sort Criteria and in the Layouts, you have the option to select a Layout. A Layout specifies how the query must be rendered.
7) First, we need to specify our Filters. Click on the “Add a new Filter” link.
8) There are many Content Types in the Orchard, but we want to restrict the result to the Tickets. So the first filter that we will add is “Content Types” in the “Content” category. Click on it and in the new Edit Filter page, select Ticket Content Type and then click on the Save button.
9) The second filter is “Current User Permissions” filter which is located in the “ContentItemPermission Fields” category. It restricts the result to the items that the user has access to them. Including such filter in the Query is necessary, otherwise users gets error message in case the result contains tickets that the logged in user doesn’t have access to them.
10) The third filter is related to the new field we added in the previous section. You can find it in the “Ticket Part Content Fields” category. Click on the Filter.
11) In the filter page, select the “Equal to” operator and enter one of the values you provided for the Field in the previous section for the Value textbox. Then click on Save button.
Next step is selecting a Layout for the Query.
1) First, delete the default Layout. Then click on the “Add a new Layout”.
2) Here, select the Ticket List layout, then click on the Save and then on the Close button. Again, in the Query page, click on the Close button to finalize creation of the Query.
Next step is creating a Projection.
1) In the Orchard dashboard, in the “New box” click on the Projection.
Enter the following values for the corresponding fields
- Title :”[Name of the Component you selected for the query filter]”
- Items to display: 20
- For Query: “[Name of the query you have created in previous step]”
- Show Pager: ticked
- Show on a menu: ticked
- Menu; ”Main Operator Menu”
- Menu Text: “[Name of the Component you selected for the query filter]”
Tip: The Menu option will be visible in case you tick the “Show on a menu” checkbox.
3) Final step is clicking on the Save button.
The Projection has been added to the Operator menu. It means any user with Operator permission is able to view the link on the top toolbar. If you click on the “Instance name” on top left corner of the Orchard-dashboard, you will return back to the front-end. Here you will see the new menu in the top toolbar. After creating some tickets and navigating to the Projection, it will look like this.
In the next posts, I will try to show more hidden features of Orchard and Orchardcollaboration.