v0.7.6

API v1 to v2 migration guide

Ticketing API v1 to v2 Migration Guide

This guide helps API consumers migrate from Ticketing API v1 client libraries to v2.

Overview

The v2 clients introduce important changes in custom field handling and serialization. Both Java and Go clients are affected.

Client Libraries:

  • Java: //pkg/mas-stack/oss/mas-ticketing/client/java/v2:api-client
  • Go: //pkg/mas-stack/oss/mas-ticketing/client/go/v2

Breaking Changes

1. Custom Fields Format (DoTransition)

v1 Format (deprecated):

json
{
  "transitionId": 111,
  "external_system_name": "Orange",
  "other_custom_field": "value"
}

v2 Format (required):

json
{
  "transitionId": 111,
  "customFields": {
    "external_system_name": "Orange",
    "other_custom_field": "value"
  }
}

2. Serialization Library (Java Only)

v1: Uses Gson for JSON serialization v2: Uses Gson for JSON serialization (consistent with v1)

Note: While the OpenAPI generator default is Jackson, our v2 clients are configured to use Gson to maintain compatibility with existing dependencies.

Migration Steps

Java Client

1. Update Dependencies

In your BUILD.bazel:

python
# Old
deps = [
    "//pkg/mas-stack/oss/mas-ticketing/client/java/v1:api-client",
]

# New
deps = [
    "//pkg/mas-stack/oss/mas-ticketing/client/java/v2:api-client",
]

2. Update Imports

java
// Old
import com.masmovil.ticketing.client.api.TicketApi;
import com.masmovil.ticketing.client.model.Ticket;

// New - package names are the same, but verify your IDE imports
import com.masmovil.ticketing.client.api.TicketApi;
import com.masmovil.ticketing.client.model.Ticket;

3. Update DoTransition Calls

Before (v1):

java
TicketApi api = new TicketApi();
SendCommsTransitionExample request = new SendCommsTransitionExample();
request.setTransitionId(111);
// Custom fields at top level - WRONG in v2
request.put("external_system_name", "Orange");
request.put("comments", "Transition comment");

api.doTransition(org, ticketId, "TGJ", request);

After (v2):

java
TicketApi api = new TicketApi();
SendCommsTransitionExample request = new SendCommsTransitionExample();
request.setTransitionId(111);

// Custom fields in nested object
Map<String, Object> customFields = new HashMap<>();
customFields.put("external_system_name", "Orange");
customFields.put("comments", "Transition comment");
request.setCustomFields(customFields);

api.doTransition(org, ticketId, "TGJ", request);

Go Client

1. Update Dependencies

In your BUILD.bazel:

python
# Old
deps = [
    "//pkg/mas-stack/oss/mas-ticketing/client/go/v1:go_default_library",
]

# New
deps = [
    "//pkg/mas-stack/oss/mas-ticketing/client/go/v2:go_default_library",
]

2. Update Imports

go
// Old
import ticketing "pkg/mas-stack/oss/mas-ticketing/client/go/v1"

// New
import ticketing "pkg/mas-stack/oss/mas-ticketing/client/go/v2"

3. Update DoTransition Calls

Before (v1):

go
api := ticketing.NewAPIClient(config).TicketApi

request := ticketing.SendCommsTransitionExample{
    TransitionId: 111,
}
// Custom fields at top level - WRONG in v2
request["external_system_name"] = "Orange"
request["comments"] = "Transition comment"

api.DoTransition(ctx, org, ticketId, "TGJ").Body(request).Execute()

After (v2):

go
api := ticketing.NewAPIClient(config).TicketApi

customFields := map[string]interface{}{
    "external_system_name": "Orange",
    "comments": "Transition comment",
}

request := ticketing.SendCommsTransitionExample{
    TransitionId: ticketing.PtrInt32(111),
    CustomFields: customFields,
}

api.DoTransition(ctx, org, ticketId, "TGJ").Body(request).Execute()

Testing Your Migration

Create a Test Case

We recommend adding tests to verify your migration works correctly:

Java Example:

java
@Test
public void testTransitionWithCustomFields() throws ApiException {
    TicketApi api = new TicketApi();

    SendCommsTransitionExample request = new SendCommsTransitionExample();
    request.setTransitionId(111);

    Map<String, Object> customFields = new HashMap<>();
    customFields.put("external_system_name", "Orange");
    request.setCustomFields(customFields);

    // Verify serialization produces correct JSON
    ObjectMapper mapper = new ObjectMapper();
    String json = mapper.writeValueAsString(request);

    assertTrue(json.contains("\"customFields\""));
    assertTrue(json.contains("\"external_system_name\":\"Orange\""));
    assertFalse(json.contains("\"external_system_name\":\"Orange\",\"transitionId\""));
}

Go Example:

go
func TestTransitionWithCustomFields(t *testing.T) {
    customFields := map[string]interface{}{
        "external_system_name": "Orange",
    }

    request := ticketing.SendCommsTransitionExample{
        TransitionId: ticketing.PtrInt32(111),
        CustomFields: customFields,
    }

    // Verify serialization
    jsonBytes, err := json.Marshal(request)
    require.NoError(t, err)

    var parsed map[string]interface{}
    err = json.Unmarshal(jsonBytes, &parsed)
    require.NoError(t, err)

    // Assert nested structure
    assert.Contains(t, parsed, "customFields")
    customFieldsParsed := parsed["customFields"].(map[string]interface{})
    assert.Equal(t, "Orange", customFieldsParsed["external_system_name"])
}

Compatibility Period

  • v1 clients: Still available but deprecated. Use for existing code only.
  • v2 clients: Recommended for all new development.
  • Backend support: The API backend currently accepts both formats, but v1 format will be removed in a future release.

Common Migration Issues

Issue: Custom fields not being sent

Symptom: Transitions work but custom fields are missing in Jira.

Cause: Using v1 pattern (top-level fields) with v2 client.

Solution: Ensure custom fields are in the customFields nested object.

Issue: Compilation errors after updating dependency

Symptom: Cannot find symbol or missing method errors.

Cause: API signatures may have minor differences between v1 and v2.

Solution: Check the generated API documentation in docs/ folder of the client library.

Issue: Tests failing after migration

Symptom: JSON serialization tests fail.

Cause: Test expectations based on v1 format.

Solution: Update test expectations to match v2 format with nested customFields.

Need Help?

  • Slack: #mas-ticketing
  • Jira: Create a ticket in the MTIC project
  • Documentation: See TechDocs
  • API Reference: Check the Swagger UI in your environment

Rollback Plan

If you encounter critical issues:

  1. Revert your BUILD.bazel dependency to v1
  2. Report the issue to #mas-ticketing with:
    • Error messages
    • Code snippet showing the issue
    • Environment (dev/sta/prod)
  3. Keep your code changes ready for when the issue is resolved

Additional Resources