The kotlin Insight Api

LICENSE

Apache License

In short:

Do whatever you want with this api, use it personally, use it commercial, copy it, modify it, redistribute it and you don't have to write my name below your app :) Hopefully it helps you having fun with developing kotlin and using Jira Insight.

My the force be with you

Import this gradle project as git-source-dependency

settings.gradle.kts

    sourceControl {
        gitRepository(uri("https://github.com/betacore/kotlin-insight-api.git")){
            producesModule("com.coop-technologies:kotlin-insight-api")
        }
    }

build.gradle.kts

    dependencies {
        ...
        // verion = "1.0" stands for the git-tag inside the master branch
        implementation(group = "com.coop-technologies", name = "kotlin-insight-api", version = "1.0")
    }

Description

This kotlin-insight-api is a wrapper around the Jira Insight Plugin Rest interface which manages assets. It shall help to build easy communication between an kotlin app and the plugin data.

You can find full examples here.

Initialze the Connection (Singleton)

Before using the api, you have to initialize the service once.

    val schemaId = 1
    val insightAuthToken = "Your-defined-auth-token"
    InsightCloudApi.init(schemaId, insightAuthToken)

Creating the mapping model

Create a regular kotlin class, which matches the insight attributes with first letter lowerCase for example an insight object Person with attributes Id, Name, Firstname, Lastname

Simple example

    // The data class to map the insight object into
    data class MyPersonClass(
        override var name: String,
        var firstname: String,
        var lastname: String
    ) : InsightEntity()

    // register the class to the name of the insight object type
    // InsightCloudApi.registerClass(theKotlinClass, nameOfTheInsightSchemaType)
    InsightCloudApi.registerClass(MyPersonClass::class.java, "Person")

Complex example

    data class MyPersonClass(
        override var name: String,
        var firstname: String,
        var lastname: String,
        var address: MyAddressClass
    ): InsightEntity()
    
    data class MyAddressClass(
        override var name: String,
        var street: String,
        var number: Int,
        var postalCode: String,
        var country: MyCountryClass // for references in Insight use Int for getting Id, String for getting Name, or use an object class
    ): InsightEntity()
    
    // register classes
    InsightCloudApi.registerClass(MyPersonClass::class.java, "Person")
    InsightCloudApi.registerClass(MyAddressClass::class.java, "Address")

Working with objects

Find all objects of a registered class

    val persons = InsightFactory.findAll<Person>()

Find object by id

    val person = InsightFactory.findById<Person>(53)

Find object by name

    val person = InsightFactory.findByName<Person>("Insight-Name")

Find object by iql

    val persons = InsightFactory.findByIQL<Person>("\"Lastname\"=\"MyLastname\"")

Creating objects

    val myPerson = Person("MyPerson", "MyFirstname", "MyLastName")
    myPerson.save() // if id is not set it will be created, else will be update, save() overrides the id of the object

Updating objects

    val person = InsightFactory.findById<Person>(1)
    person.firstname = "AnotherFirstname"
    person.save()   // if id is set (by loading or save(), it will be updated, without set id it will be created

Deleting objects

    val person = InsightFactory.gindById<Person>(1)
    person.delete()   // will only be deleted if id is set

Working with object history

Get history of an object

    val person = InsightFactory.findById<Person>(1)
    val history = person.getHistory()

Working with attachements

Get attachment objects of an object

    val person = InsightFactory.findByName<Person>("MyPerson")
    val attachments = person.getAttachments()

Download attachment

    val person = InsightFactory.findByName<Person>("MyPerson")
    val attachments = person.getAttachments()
    val attachment = attachments.first()
    val downloadedBytes = attachment.getBytes() // this starts the download and returns the bytes

Create/Upload attachment

    val person = InsightFactory.findById<Person>(1)
    val myFile = File("pathToFile")
    person.addAttachment("filename.txt", myFile.readBytes(), "MyComment")

Delete attachment

    val person = InsightFactory.findByName<Person>("MyPerson")
    val attachments = person.getAttachments()
    val attachment = attachments.first()
    attachment.delete()