|
| 1 | +# OBP to CBP migration |
| 2 | + |
| 3 | +Zendesk is [obsoleting](https://support.zendesk.com/hc/en-us/articles/4408846180634-Introducing-Pagination-Changes-Zendesk-API#h_01F7Y57A0G5M3R8JXGCQTBKVWA) Offset Based Pagination (OBP), it's recomended to start adopting Cursor Based Pagination (CBP). This SDK have created pagination Iterators to help facilite the change. |
| 4 | + |
| 5 | +To use the pagination iterator, start with `NewPaginationOptions()` function, it will return a `PaginationOptions` object, you can specify the default page size in `PageSize` variable. By default, `PageSize` is 100. Then you can call the `client.GetXXXXXIterator(ctx, ops)` to return an object pagination iterator, with the iterator, you can iterator through the objects with `HasMore()` and `GetNext()` until `HasMore` return `false`. |
| 6 | + |
| 7 | +```go |
| 8 | +ops := NewPaginationOptions() |
| 9 | +// ops.PageSize = 50 // PageSize can be set to 50 |
| 10 | +it := client.GetTicketsIterator(ctx, ops) |
| 11 | +for it.HasMore() { |
| 12 | + tickets, err := it.GetNext() |
| 13 | + if err == nil { |
| 14 | + for _, ticket := range tickets { |
| 15 | + println(ticket.Subject) |
| 16 | + } |
| 17 | + } |
| 18 | +} |
| 19 | +``` |
| 20 | + |
| 21 | +If the API endpoint requires more options like organization ID, it can be set into the `Id` attribute like below example: |
| 22 | + |
| 23 | +```go |
| 24 | +ops := NewPaginationOptions() |
| 25 | +ops.Sort = "updated_at" |
| 26 | +ops.PageSize = 10 |
| 27 | +ops.Id = 360363695492 |
| 28 | +it := client.GetOrganizationTicketsIterator(ctx, ops) |
| 29 | + |
| 30 | +for it.HasMore() { |
| 31 | + tickets, err := it.GetNext() |
| 32 | + if err == nil { |
| 33 | + for _, ticket := range tickets { |
| 34 | + println(ticket.Subject) |
| 35 | + } |
| 36 | + } |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +For any API specific parameters, they are predefined in the `CommonOptions` struct, we can set these attributes in the `PaginationOptions` object. |
| 41 | +If new attributes are introduced to any existing or new API endpoints, it can be added into this struct. |
| 42 | + |
| 43 | +```go |
| 44 | +type CommonOptions struct { |
| 45 | + Active bool `url:"active,omitempty"` |
| 46 | + Role string `url:"role,omitempty"` |
| 47 | + Roles []string `url:"role[],omitempty"` |
| 48 | + PermissionSet int64 `url:"permission_set,omitempty"` |
| 49 | + |
| 50 | + // SortBy can take "assignee", "assignee.name", "created_at", "group", "id", |
| 51 | + // "locale", "requester", "requester.name", "status", "subject", "updated_at" |
| 52 | + SortBy string `url:"sort_by,omitempty"` |
| 53 | + |
| 54 | + // SortOrder can take "asc" or "desc" |
| 55 | + SortOrder string `url:"sort_order,omitempty"` |
| 56 | + Sort string `url:"sort,omitempty"` |
| 57 | + Id int64 |
| 58 | + GroupID int64 `json:"group_id,omitempty" url:"group_id,omitempty"` |
| 59 | + UserID int64 `json:"user_id,omitempty" url:"user_id,omitempty"` |
| 60 | + OrganizationID int64 `json:"organization_id,omitempty" url:"organization_id,omitempty"` |
| 61 | + |
| 62 | + Access string `json:"access"` |
| 63 | + Category int `json:"category"` |
| 64 | + Include string `json:"include" url:"include,omitempty"` |
| 65 | + OnlyViewable bool `json:"only_viewable"` |
| 66 | + Query string `url:"query"` |
| 67 | + EndUserVisible bool `url:"end_user_visible,omitempty"` |
| 68 | + FallbackToDefault bool `url:"fallback_to_default,omitempty"` |
| 69 | + AssociatedToBrand bool `url:"associated_to_brand,omitempty"` |
| 70 | + CategoryID string `url:"category_id,omitempty"` |
| 71 | + |
| 72 | + IncludeInlineImages string `url:"include_inline_images,omitempty"` |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +## To regenerate CBP(Cursor Based Pagination), OBP(Offset Based Pagination) helper function and Iterators |
| 77 | + |
| 78 | +If a new API endpoint supports CBP, add a new element to the funcData in script/codegen/main.go file like this: |
| 79 | + |
| 80 | +```go |
| 81 | +{ |
| 82 | + FuncName: "Automations", |
| 83 | + ObjectName: "Automation", |
| 84 | + ApiEndpoint: "/automation.json", |
| 85 | + JsonName: "automations", |
| 86 | + FileName: "automation", |
| 87 | +}, |
| 88 | +``` |
| 89 | + |
| 90 | +should use the script to generate the helper functions and the iterator |
| 91 | +`go run script/codegen/main.go` |
| 92 | + |
0 commit comments