--- title: "Getting Started: Creating and Working with Journals, Tickets, and Follow-Ups" slug: "getting-started-creating-and-working-with-journals-tickets-and-follow-ups-1" updated: 2026-05-04T09:22:01Z published: 2026-05-19T17:03:54Z canonical: "help.idibilling.com/getting-started-creating-and-working-with-journals-tickets-and-follow-ups-1" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.idibilling.com/llms.txt > Use this file to discover all available pages before exploring further. # Getting Started: Creating and Working with Journals, Tickets, and Follow-Ups ## Prerequisites This guide assumes familiarity with the following: - Obtaining a security token to access CostGuard web services - Querying ODatas ## Introduction and Basic Terminology While CostGuard users work with journals, tickets, and follow-ups in the Tickets web and CostGuard client applications, each of these are actually Journal objects (plain or specialized), hence we’ll be working with the Journals API throughout this guide. **Tickets** (a.k.a. Trouble Tickets) track problems and resolutions, either for pieces of equipment, individual customers, or multiple customers (the latter referred to as **Global Tickets**.) Tickets have their own lifecycle, and may be tied to a CostGuard workflow. Tickets may also be nested in a parent/child hierarchy. They may also be placed on hold and later resumed, stopping the clock so as to not count against SLAs when waiting, for example, as customer or vendor response. **Follow-Ups** are actionable items with their own lifecycle. They may be added directly to a customer account or to any ticket. **Journals** are used to store notes and other miscellaneous information on a customer account. Journals may be added directly to customer accounts, or may be added to specific trouble tickets or to follow-ups. **Journal Item** is the generic base term for Journals, Follow-Ups, and Tickets. **DISCLAIMER**: The included code snippets are only meant to serve as pseudo code and are not intended to be compilable as is. For more specific code examples, please refer to the sample project. ## Creating Journal Items ### Basic structure of a Create Journal API Request The following C# snippet is the basic outline for the creation of journals, follow-ups, and tickets. Note the use of the **CreateJournalItemReq, CreateJournalItemRequest, and CreateJournalItemResponse** container objects. ```plaintext //Obtain a requestor object (see the IDI Authentication user guide) Requestor requestor = new Requestor(); //Obtain a security token Context context = await SimpleWebTokenAccess.CreateSWT(); //Create a Channel object for the Journal web service using the appropriate endpoint address. ChannelFactory factory = new ChannelFactory("JournalServicePort", endpointAddress); JournalServicePortTypeChannel channel = factory.CreateChannel(); requestor.AuthorizationToken = "AuthorizationToken"; //Populate the request details //When creating Journals, Follow-ups, or Tickets, the request type is always CreateJournalItemReq CreateJournalItemReq req = new CreateJournalItemReq() { CreateJournalItem = new CreateJournal() //CreateFollowUp = new CreateFollowUp() //CreateTicket = new CreateTicket() { // Required and Optional Properties // See specific examples of creation objects in the Common Tasks section } }; //Create a request wrapper CreateJournalItemRequest request = new CreateJournalItemRequest(requestor, req); //submit the request CreateJournalItemResponse response = channel.CreateJournalItem(request); //Error handling if (response.Messages != null) { Console.WriteLine("The following errors have occurred:"); foreach (var msg in response.Messages) { Console.WriteLine(msg.MessageMember); } } else { Console.WriteLine("New JournalItemID: " + response.Result.JournalItem.JournalItemID) Console.WriteLine("No errors occurred."); } ``` ### Common Required Properties Whether using CreateJournal(), CreateFollowUp(), or CreateTicket(), this property is required: - **JournalItemTypeID** – *JournalItemTypeID OData for valid values specific to Journals, Follow-Ups, and Tickets* ### Other Common Properties - **Description** - For a journal, the Description is effectively the journal entry - For follow-ups and tickets, this is the full writeup - Tickets have a separate Title property (covered later) that serve as a short version of the Description - Description is required for Tickets; for Journals and Follow-Ups, if not supplied, the Description will default to the Journal Type name - **IsInternal** – Internal journals are not exposed to OnlineBill customers. Defaults to False if not specified. - **IsRetained** – Exposes the journal/follow-up/tickets in the Customer Summary view (CostGuard Client) and InfoCenter (Tickets Web App). Defaults to False if not specified. - **JournalItemStatusID** - Required for Tickets, but optional/informational for Journals and Follow-Ups - *See JournalItemStatusID OData for valid values* - **ObjectType & ObjectID** *– see table* | **ObjectType enum** | **ObjectID** | | --- | --- | | Customer | The CustomerID of the customer to which the journal/ticket/follow-up is being added | | BillingOrder | Any system OrderID (carts in the older Ordering module) | | Equipment | The EquipmentID of the inventory item to which the journal/ticket/follow-up is being added | | JournalItem | If adding a journal to a follow-up, the Follow-up ID. If adding a journal or follow-up to a Ticket, the TicketID. If adding a child trouble ticket, the TicketID of the parent ticket. | ## Creating Journal Items ### Creating a Journal This example creates a simple journal on the customer’s record. Because IsRetained is set to True, this journal would show in the Customer Summary and InfoCenter areas of the CostGuard Client/Tickets web module. ```plaintext CreateJournalItem = new CreateJournal() { Description  = "This is an excellent customer journal", IsRetained = true, // Displays in InfoCenter JournalItemTypeID = 1013 // Type must be of Journal Class "Journal" ObjectID = 1407, // Assumes CustomerID 1407 exists in Core database ObjectType = ObjectType.CustomerID } ``` ### Creating a Follow-Up This example creates a follow-up for an existing order. Two more properties are required when creating follow-ups: - **ActionDate** – When action should be taken by the analyst for the follow-up - **AssignedUser** – Initial user responsible for the follow-up. Note this does not have to be an existing CostGuard user account, though the GUIs may enforce your end users to change it to one eventually. ```plaintext CreateJournalItem = new CreateFollowUp() { ActionDate = DateTime.Now.AddDays(3), //Follow-Up date in the GUI AssignedUser = "APITest", Description  = "Remind customer of 4Q End discount", JournalItemTypeID = 1002 // Type must be of Journal Class "Follow-Up" ObjectID = 10516, // OrderID ObjectType = ObjectType.BillingOrder } ``` ### Adding a Journal to a Follow-Up Building off the last two examples, here is how to add a journal to the follow-up: ```plaintext CreateJournalItem = new CreateJournal() { Description  = "This is a REALLY good deal", JournalItemTypeID = 1013, // Type must be of Journal Class "Journal" ObjectID = 197, // Captured/looked-up JournalItemID of the follow-up created above ObjectType = ObjectType.JournalItem } ``` ### Creating a Ticket Creating a ticket requires the same properties to be supplied as for follow-ups, plus: - **PriorityID** – *See TicketPriority OData for valid values* - **TicketClass** – *see table* | **TicketClass enum** | **Description** | | --- | --- | | Customer | Customer-related issue | | Email | Unsolicited, or “cold” communications; when configured along | | Equipment | Equipment-related issue | | StandAlone | Not global, not tied to any other entity in particular (included for legacy CostGuard compatibility) | | Global | Affects all customers and equipment | Here is an example of creating a customer-assigned ticket: ```plaintext CreateJournalItem = new CreateTicket() { ActionDate = DateTime.Now.AddDays(3), //Follow-Up date in the GUI AssignedUser = "APITester", Description = "Customer is missing some megahertz", JournalItemTypeID = 4, // Type must be of Journal Class "Ticket" ObjectID = 1407, ObjectType = ObjectType.Customer, PriorityID = 1, TicketClass = TicketClass.Customer } ``` And an example of creating a global ticket: ```plaintext CreateJournalItem = new CreateTicket() { ActionDate = DateTime.Now.AddDays(3), //Follow-Up date in the GUI AssignedUser = "APITester", Description = "All customers are missing gigahertz!!", JournalItemTypeID = 4, // Type must be of Journal Class "Ticket"     PriorityID = 1, TicketClass = TicketClass.Global } ``` ## Editing Journal Items ### Basic structure of a Modify Journal API Request Below is the outline for editing journal items; it is essentially the same structure as in the Create examples from earlier, except it uses the **ModifyJournalItemReq, ModifyJournalItemRequest, and ModifyJournalItemResponse** container objects. ```plaintext //Obtain a security token Context context = await SimpleWebTokenAccess.CreateSWT(); //Create a Channel object for the Journal web service using the appropriate endpoint address. ChannelFactory factory = new ChannelFactory("JournalServicePort", endpointAddress); JournalServicePortTypeChannel channel = factory.CreateChannel(); Requestor requestor = new Requestor(); requestor.AuthorizationToken = "AuthorizationToken"; ModifyJournalItemReq req = new ModifyJournalItemReq() { myJournalItem = new JournalServiceReference1.JournalItem //myFollowUp = new JouranlServiceReference1.FollowUp //myTicket = new JournalServiceReference1.Ticket { // Required and Optional Properties // See specific examples of modify objects in the Common Tasks section } }; ModifyJournalItemRequest request = new ModifyJournalItemRequest(requestor, req); ModifyJournalItemResponse response = channel.ModifyJournalItem(request); if (response.Messages != null) { Console.WriteLine("The following errors have occurred:"); foreach (var msg in response.Messages) { Console.WriteLine(msg.MessageMember); } } else { Console.WriteLine("No errors occurred."); } ``` ### Editing a Journal To edit a journal simply requires the **JournalItemID** of the journal, plus any desired property updates. Unspecified properties will be left alone upon edit. ```plaintext JournalItem = new JournalServiceReference1.JournalItem { Description = "Check in after New Year’s.", JournalItemID = 198 } ``` ### Editing a Follow-Up Modifying follow-ups are a similar prospect. ```plaintext JournalItem = new JournalServiceReference1.FollowUp { ActionDate = Convert.ToDateTime("1/2/2018"), Description = "Check in after New Year’s.", JournalItemID = 199 } ``` ### Editing a Ticket This ticket edit example illustrates setting new informational properties, **ReferenceNumber** and **TrackingNumber**. ```plaintext JournalItem = new JournalServiceReference1.Ticket { JournalItemID = 203, ReferenceNumber = "ABC123", TrackingNumber = "XYZ789", } ``` ## Deleting Journal Items ### Basic structure of a Delete Journal API Request Deleting Journal Items also uses the ModifyJournalItem container objects. Setting the appropriate Journal Item class and JournalItemID is done in the same manner as with Edits; the key difference is the **Remove** property that gets set to *true* on the ModifyJournalItemReq object. ### Deleting a Journal ```plaintext ModifyJournalItemReq req = new ModifyJournalItemReq() { JournalItem = new JournalServiceReference1.Journal { JournalItemID = 200 } }; req.Remove = true; ``` ### Deleting a Follow-Up ```plaintext ModifyJournalItemReq req = new ModifyJournalItemReq() { JournalItem = new JournalServiceReference1.FollowUp { JournalItemID = 201 } }; req.Remove = true; ``` ### Deleting a Ticket ```plaintext ModifyJournalItemReq req = new ModifyJournalItemReq() { JournalItem = new JournalServiceReference1.Ticket { JournalItemID = 202 } }; req.Remove = true; ``` ## Additional Ticket-specific Operations ### Updating a Ticket’s Status ```plaintext JournalItem = new JournalServiceReference1.Ticket { JournalItemID = 202, JournalItemStatusID = "1002" } ``` ### Placing a Ticket On Hold Setting any **HoldReasonID** property (*see the TicketHoldReason Odata for valid values)* will place the ticket “On Hold”. (This is also referred to as “parking” the ticket.) ```plaintext JournalItem = new JournalServiceReference1.Ticket { JournalItemID = 206, HoldReasonID = "1" //id as string;  Waiting on Customer action } ``` ### Resuming an On Hold Ticket Resume the On Hold ticket by setting the **HoldReasonID** to any empty string. ```plaintext JournalItem = new JournalServiceReference1.Ticket { JournalItemID = 206, HoldReasonID = "" //clear the On Hold status by setting to empty string } ``` ### Closing a Ticket Closing a ticket (after which no modifications may be made to it) involves setting the **Close** property to true. Setting the **JournalItemStatusID, ResolutionTypeID, ResolutionNote** at this time is also recommended. *See the TicketResolutionType Odata for possible values.* ```plaintext JournalItem = new JournalServiceReference1.Ticket { Close = true, JournalItemID = 202, JournalItemStatusID = "1005", //may differ per system, as custom statuses allowed ResolutionNote = "All's well that ends well.", ResolutionTypeID = "10001" //int as string } ``` ### Assigning a Customer to a Ticket after the fact The **Email** Ticket Class is useful for tracking unsolicited, or “cold” emails in the CostGuard system. If the contact later becomes a customer (or it is later realized that the email address from which the ticket was created belongs to an existing customer), simply assign the ticket to the customer with the ObjectID and ObjectType as before in the Create examples. ```plaintext JournalItem = new JournalServiceReference1.Ticket { JournalItemID = 207, ObjectID = 1407, ObjectType = ObjectType.Customer } ``` ## Miscellaneous Points Some extra pointers and things to be aware of. ### Nullable Types The nullable types in the service definition may be submitted as those types for the CreateJournal methods, however some of these properties you may see are of type (an IDI custom type) when submitting Modify requests, and will need to be cast as strings. An example of this is the non-required *JournalItemStatusID* property. On a Modify: - if set to null then the WS will treat it like no change - if you want to clear the status you would send an empty string - if you want to set it to another value you would send the int value in string format ### API vs GUI business rules The CostGuard Client and Ticket GUIs enforce additional business logic and required fields that the create and modify endpoints do not. For example, the GUI requires that Status and Title be supplied when creating a ticket, but the API submission will go through using the minimum properties from the above examples. ### The All-powerful Delete There are currently no restrictions in the APIs for ticket deletion—even closed tickets can be deleted with the web service user. ### Setting and Modifying Journal Item Attributes If you have an attribute definition associated with your journal type you can use the Journal service’s **ModifyExtendedInformation** operation to set the key/value pairs. ## Code Sample Project The sample project can be downloaded from the link below: [Getting Started with IDI Web Services Sample Project](/v1/docs/getting-started-with-idi-web-services-sample-project-2)