Introduce Ballerina Connector for Jira

[NipunaRanasinghe]

Need to introduce a Ballerina connector for Jira.

Related links:

• https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/
• https://developer.atlassian.com/cloud/jira/platform/swagger-v3.v3.json

Please consider the following tasks:

1. create a new repository under 'ballerina-platform' organization.
2. Review and sanitize the OpenAPI specification
3. Generate the connector client
4. Implement a test suite covering the core functionalities
5. Write documentation with examples

[Jaagrav]

Hi I am interested in working on this task

[asmi55]

Hi since this got unassigned can I take over this issue?

[MohamedSabthar]

👋 Welcome, @asmi55! 🚀

We're thrilled to have you join the Ballerina Hacktoberfest community! The issue has been assigned to you, and we’re excited to see your contributions.

To help you get started, here are a few essential resources:

1. Connector Contributor Guide: Make sure to go through our Ballerina Hacktoberfest connector contributor guidelines and follow the exact steps, to contribute effectively.
2. Learn Ballerina: Whether you're new to Ballerina or looking to enhance your skills, check out our official learning resources.
3. Community & Support: If you have technical questions, feel free to ask on Stack Overflow with the Ballerina tag, or join us on Discord to connect with other community members.

No contribution is too small, and your feedback is always welcome! Don’t hesitate to ask questions, propose new ideas, or report issues.

We are currently in the process of creating a GitHub repository for this connector module and will update you once it’s available. In the meantime, please go through the relevant resources and documentation related to the connector.

Happy coding and welcome aboard! 🎉

[Bhashinee]

Hello, @asmi55,

I'll be mentoring your project, and we have created the repository for your connector project with the initial project template. You can start working in this repository: https://github.com/ballerina-platform/module-ballerinax-jira

Please refer to the contribution process section for guidelines on raising a PR: https://ballerina.io/hacktoberfest/connector-contributor-guide/#contribution-process.

Happy coding! 🎉

[Bhashinee]

Hi @asmi55, greetings from the Ballerina team! 👋

I wanted to check in on the progress of the Ballerina Jira Connector development. I hope everything is on track and that you’ve started the connector development.

If you need any help or have questions, feel free to comment here!

Happy coding!

[AnsarMahir]

@Bhashinee I would like to take this up if no updates from the assigned person :)

[Bhashinee]

Hello @AnsarMahir I appreciate your interest in this project. If the original assignee does not respond within the next one or two days, we will assign the issue to you. :)

[asmi55]

Hey @Bhashinee apologies for the delay, I'm a bit caught up with some other tasks atm, sorry for not informing earlier. Feel free to go ahead and assign @AnsarMahir!

[Bhashinee]

Hi @asmi55 Thank you for letting us know.

@AnsarMahir, I assigned the issue to you. You can work on it now. Happy coding! :)

[AnsarMahir]

Hey @Bhashinee. I just checked the Jira OpenAPI specification. There are many errors in the specification according to swagger editor. Below are some examples

"Semantic error at paths./rest/api/3/classification-levels.get.parameters.0.schema.items.default Default values must be present in enum

Semantic error at paths./rest/api/3/field/search.get.parameters.2.schema.items.default Default values must be present in enum

Semantic error at paths./rest/api/3/issue/limit/report.get.requestBody GET operations cannot have a requestBody.

Semantic error at paths./rest/api/3/issue/properties/{propertyKey}.delete.requestBody DELETE operations cannot have a requestBody. "

1) I think it is better to fix this errors before generating the client. So in the case of "Default values must be present in enum", is it okay to add an element from the enum to "default" attribute or is it okay to remove the "default" attribute, which approach is acceptable ??

in the other cases where a requestBody cannot be part the request, is it okay to remove it ??

Or can i just move on ignoring these issues to generate the client ??

2)Another issue is there are lot of deprecated methods(endpoints), can i remove those from the specification?

[Bhashinee]

Hi @AnsarMahir,

1. Let's not do anything where the error says Default values must be present in enum as it is automatically handled at the Ballerina client generation step. However, we should remove the request body from all GET operations. No need to remove the request body from the Delete operations, as it is handled by the client.
2. It is better to remove them and sanitize the OpenAPI specification. To remove them, you have to go through their guide and make the necessary replacements. In most cases, it only requires removing the field, but please verify by reviewing the documentation to ensure accuracy.

[AnsarMahir]

Hey @Bhashinee Checkout the PR PR for client generation and sanitation

[AnsarMahir]

Hey @Bhashinee , Right now, I'm stuck on the build process. So, after generating the client, I tried to use the gradle build, which throwed an error "There is no Dependencies.toml". So I searched find out that I have to go into the ballerina directory and use "bal pack" to get that file.

Then I proceeded with that and it generated the Dependencies.toml. After that , I tried running the gradle build and it started to fail as below

` PS D:\ballerina\module-ballerinax-jira> ./gradlew clean build

Configure project :jira-ballerina [Info] project builds on docker [Info] using the Ballerina docker image tag: 2201.10.0

Task :jira-ballerina:build FAILED

Task :jira-ballerina:commitTomlFiles On branch main Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

FAILURE: Build failed with an exception.

• What went wrong: Execution failed for task ':jira-ballerina:build'.

  java.io.FileNotFoundException: D:\ballerina\module-ballerinax-jira\ballerina\build\bal_build_target\bala`

So the bal pack command actually creates that file, but not in the directory which is searched in the build process, rather the file is created in the directory D:\ballerina\module-ballerinax-jira\ballerina\target\bala

So, What is the right approach I should take now to overcome this ?

Note: The same error pops up even without doing client generation. So to recreate the issue, Try out by cloning the repo and building it

[Bhashinee]

I checked out your PR and tried building the project locally, and it worked fine. Did you follow the steps given here? https://ballerina.io/learn/create-your-first-connector-with-ballerina/

1. As given in the prerequisites section, do you have the Ballerina latest version(2201.10.2) installed?
2. Step 1 given in the above link is already done for you, you can clone the Jira repository to get that. And you have to carry out the steps from Step 2 onwards.

If it gives the same error even after following the steps given in the above mentioned link, could you please navigate to the ballerina folder in the jira connector project(D:\ballerina\module-ballerinax-jira\ballerina) and execute bal build command and check the output?

[Bhashinee]

Hey @AnsarMahir!

Hope everything’s going well so far! Just a quick update on the project deadlines: it's set for one month from the day you were officially assigned. But if you encounter any challenges or unforeseen issues, please feel free to reach out, and we can consider adjusting the deadline accordingly.

If you have any questions or need help with anything, please feel free to reach out. Keep up the awesome work! 🚀

[AnsarMahir]

Hey @Bhashinee stuck on mid exams and uni stuff. Will catch up with the progress ASAP. Thanks for the reminder :)

[AnsarMahir]

Hey @Bhashinee , I was able to write a test successfully. But in the 2nd test, writing for the below one, I'm bit stuck

resource isolated function get rest/api/'3/mypermissions(map<string|string[]> headers = {}, *GetMyPermissionsQueries queries) returns Permissions|error { string resourcePath = string/rest/api/3/mypermissions; resourcePath = resourcePath + check getPathForQueryParam(queries); return self.clientEp->get(resourcePath, headers); }

So the response is recieved as a "Permission" type response,

function testGetMyPermissions() returns error? {
    GetMyPermissionsQueries queryParams = {
        permissions: "BROWSE_PROJECTS"
    };
    Permissions response = check jira->/rest/api/'3/mypermissions(queries = queryParams);

The response that we receive is like the below one,

    {"permissions":{"BROWSE_PROJECTS":{"id":"10","key":"BROWSE_PROJECTS","name":"Browse 
    Projects","type":"PROJECT","description":"Ability to browse projects and the issues within them.","havePermission":true}}}

I'm not able to navigate to the 'havePermission' field, Tried using dot operator to move in but no luck. Can you let me know the right way to do this ??

FYI, this permission is a closed record type, `public type Permissions record {|

List of permissions.

record {|UserPermission...;|} permissions?;

|};`

[Bhashinee]

You can access the havePermission field as follows,

boolean? havePermission = response?.permissions["BROWSE_PROJECTS"]?.havePermission;

[AnsarMahir]

@Bhashinee did a PR for tests also

[Bhashinee]

@AnsarMahir

Thanks for your contributions! We’ll review the PR as soon as possible. During the review, we may suggest some changes, so please address those as they come up.

[Bhashinee]

@AnsarMahir

Looking at the PR I saw that you've added 5 mock test cases. However you haven't added the mock service implementations in the PR. You need to add that. And also, it is better if we can have at least 20 test cases covered.

You can easily generate a mock service skeleton that can be used as the test service, providing the open API spec using the Ballerina OpenAPI tool command bal openapi -i <openapi-contract> --mode service

Then you can keep only the resource functions related to the APIs you choose to test and remove everything else.

Furthermore, we expect at least one example to be written in this project as given in the guide section 5 step 3. Step 6 does not need to be done by you

And please manually test at least a couple of connector APIs against the live environment as well. You may need to create an account in Jira and get the tokens for that.

[AnsarMahir]

@Bhashinee all those 5 test cases are manually tested for live server. I will do the rest as per your comments. Thanks

[Bhashinee]

@Bhashinee all those 5 test cases are manually tested for live server. I will do the rest as per your comments. Thanks

Nice!!! :)

[AnsarMahir]

@Bhashinee added 20 test cases, all of them are tested and verified, go through and let me know your comments

[AnsarMahir]

@Bhashinee finished. Examples are not added as they are optional. All the test cases are tested. Let me know if any changes to be done

[NipunaRanasinghe]

@AnsarMahir we expect to have atleast 1 (2 recommended) examples for any given connector. Appreciate if you can prioratize that as well.

[AnsarMahir]

@NipunaRanasinghe will look into that :)

[AnsarMahir]

@NipunaRanasinghe added an example. Not pretty sure how far its gonna work as there is a compilation error stating that (Undefined resource path, because that path is not in the ballerinax/jira still), So was not able to test it is working or not, If you know any workaround to run the function, please let me know. BTW i will add another one or two examples after your review on the first example :)